Overview | Index by: file name | procedure name | procedure call | annotation

tcldoc.tcl Annotations

Created from tcldoc.tcl
TclDoc parses the declarations and documentation comments in a set of Tcl source files and produces a corresponding set of HTML pages describing procedure declarations. Run TclDoc on a set of files and/or directories. It builds a rich internal representation of the files, determining both procedure declarations and procedure calls. TclDoc will run on .tcl and .tsh source files that are pure stub files with no procedure bodies. This means you can write documentation comments and run TclDoc in the earliest stages of design while creating the API, before writing the implementation.
Version:
1.0
Author:
Jason Tang (tang@jtang.org)
See Also:
http://mini.net/tcl/TclDoc

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

add_summary

proc add_summary { entry target arguments source description type }
Adds an entry to the global summary table. The entry will eventually be written to the global summary indices.
Parameters:
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.
See Also:
write_index_annotations
Defined in:
tcldoc.tcl, line 910

declaration_scan

proc declaration_scan { filename }
Scans a file for all instances of lines beginning with proc indicating a procedure declaration. Add discovered declarations to the procedure table along with its line number in the file.
Parameters:
filename - file to scan for procedure declarations
Defined in:
tcldoc.tcl, line 104

deep_scan

proc deep_scan { filename }
Take a single source Tcl file and scan it intensively, generating its HTML version. Identify comment blocks and highlight them in the HTML version. If the comment is a procedure-level or file-level comment then pipe it through the scanner for annotation purposes. Identify procedure declarations, add <a name> anchors and add their parameters to the function table. Identify procedure calls and add <a href> hypertext. Substitute proper html codes for special symbols <, >, &, and ". Write the HTML marked version as well as the annotations.
Parameters:
filename - file to scan
See Also:
scan_recursively
Defined in:
tcldoc.tcl, line 139

filecomp

proc filecomp { a b }
Compares the last part of a filename (i.e., sans directory paths). Returns-1, 0, 1 if respectively $a occurs lexically before, with, or after $b.
Parameters:
a - first file to compare
b - second file to compare
Returns:
-1, 0, or 1
Defined in:
tcldoc.tcl, line 843

flatten_args

proc flatten_args { x }
Given an arbitrary length list (such as the one supplying arguments to a procedure declaration) remove excess spaces between arguments. This is very similar to Lisp's flatten function.
Parameters:
x - list to flatten
Returns:
a flattend list
Defined in:
tcldoc.tcl, line 882

get_param

proc get_param { param_list param_num param_name }
Retrives a parameter from the options list. If no parameter exists then abort with an error very reminisicent of C's getopt function; otherwise increment param_num by one.
Parameters:
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
Returns:
the $param_num'th element into $param_list
Defined in:
tcldoc.tcl, line 967

glob_all

proc glob_all { dir exts }
Glob recursively across a directory and its subdirectory for all files matching a list of extensions. Return all matches as a flat list.
Parameters:
dir - root directory to scan
exts - list of extension (e.g., *.tcl) to search
Returns:
list of matching files
Defined in:
tcldoc.tcl, line 817

initialize_tables

proc initialize_tables {  }
Initialize all of the various cross-reference tables used by TclDoc. If an import record was given then merge that record with these tables.
Defined in:
tcldoc.tcl, line 29

lookup_procrecord

proc lookup_procrecord { procname basename }
Given a procedure name, look up within the procedure table for its declaration. In case of ambiguity as to which function declaration to use prefer to use the last one declared within $basename. Otherwise just use the first one listed (and hope for the best!). Returns a two element list containing the Tcl source filename and line number where procedure was declared. If the procedure is not declared at all return an empty list.
Parameters:
procname - procedure name to look up
basename - preferred file to use
Returns:
if entry found a 2-ple procedure record, else an empty list
Defined in:
tcldoc.tcl, line 399

path_lookup

proc path_lookup { orig_file }
Given a filename returns the location of where its TclDoc'ed files are located. The path may not necessarily be the same as $::dest_dir, especially if the file is being imported from elsewhere by way of --import.
Parameters:
orig_file - filename to find
Returns:
path to where TclDoc wrote its file
Defined in:
tcldoc.tcl, line 854

prepare_destination

proc prepare_destination {  }
Creates the destination directory as necessary. Copy over the overview file (if --overview specified) and doc files (--doc-files) as necessary.
Defined in:
tcldoc.tcl, line 39

print_status

proc print_status { args }
If running in verbose mode print to standard output its arguments. Otherwise do nothing.
Parameters:
args - any valid string suitable to be passed to puts
Defined in:
tcldoc.tcl, line 870

print_tcldoc_help

proc print_tcldoc_help { chan }
Print TclDoc's usage to a channel.
Parameters:
chan - I/O channel to print usage documentation
Defined in:
tcldoc.tcl, line 979

sanitize

proc sanitize { s }
Given some text, replaces potentially dangerous characters with their HTML character code. Returns the new string afterwards.
Parameters:
s - string to sanitize
Returns:
an HTML-friendly version of $s
Defined in:
tcldoc.tcl, line 419

scan_recursively

proc scan_recursively { dest buffer basename annotname }
Given a buffer of Tcl code recursively examine each command within. Commands follow normal Tcl syntax -- they are either terminated by newlines or semicolons. If a single command has multiple parts (such as an 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.

Parameters:
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
Defined in:
tcldoc.tcl, line 221

tcldoc_args

proc tcldoc_args { argv }
Parse the command line and set global options.
Parameters:
argv - list of options from the command line
Defined in:
tcldoc.tcl, line 1023

tcldoc_error

proc tcldoc_error { message {returnvalue -1} }
Called to abort TclDoc upon all other errors. Print to standard error the error message then abort TclDoc.
Parameters:
message - message to display
returnvalue - exit code
Defined in:
tcldoc.tcl, line 953

tcldoc_file_error

proc tcldoc_file_error { message }
Called to abort whenever TclDoc discovers a problem with a particular input file. Print to standard error the message along with the source file and line number where that error occured. Finally abort program.
Parameters:
message - message to display
Defined in:
tcldoc.tcl, line 943

tcldoc_file_warning

proc tcldoc_file_warning { message }
Called whenever TclDoc found a problem with a file, particularly something that it could not parse. Print to standard error the message along with the source file and line number if verbose reporting was enabled.
Parameters:
message - message to display
Defined in:
tcldoc.tcl, line 931

tcldoc_main

proc tcldoc_main {  }
Actually run TclDoc across requested files and directories. Scan them and generate HTML markup versions. Scan file and procedure comments to build the annotated files. Cross-reference procedure calls with the declarations. Finally write indices to everything.
Defined in:
tcldoc.tcl, line 1104

write_and_update

proc write_and_update { dest output }
Writes to channel $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.
Parameters:
dest - channel to write $output
output - data to write
Defined in:
tcldoc.tcl, line 377

write_export_file

proc write_export_file {  }
Defined in:
tcldoc.tcl, line 92

write_footer

proc write_footer { dest }
Output a common header for HTML-ized Tcl files. This same footer is also used for index_main.html.
Parameters:
dest - I/O channel to write HTML footer
Defined in:
tcldoc.tcl, line 459

write_header

proc write_header { dest basename title }
Outputs a common header for HTML-ized Tcl files.
Parameters:
dest - I/O channel to write HTML header
basename - Tcl source filename, sans any directory paths
title - HTML title to use for generated file
Defined in:
tcldoc.tcl, line 432

write_index_annotations

proc write_index_annotations {  }
Write two indices of all declared procedures and source files. The big index (index_annot_full.html) alphabetizes everything and displays a one-line summary along with a hyperlink to the item. The smaller index, index_annot.html, has just the item names and hyperlinks.
Defined in:
tcldoc.tcl, line 644

write_index_bycall

proc write_index_bycall { mainindex }
Write the index of procedure calls. Alphabetically list every procedure that is called. Add hyperlinks to the line where that call is made. Also write to the main index a similar list.
Parameters:
mainindex - I/O channel of index_main.html
Defined in:
tcldoc.tcl, line 597

write_index_byfile

proc write_index_byfile { mainindex }
Write the index of filenames. Alphabetically list all source files along with procedures declared within. Add hyperlinks from those procedure names to the line where they are declared. Also write to the main index a similar list.
Parameters:
mainindex - I/O channel of index_main.html
Defined in:
tcldoc.tcl, line 487

write_index_byproc

proc write_index_byproc { mainindex }
Write the index of procedures. Alphabetically list all procedure declarations; if a procedure is declared multiple times list all of them. Add hyperlinks from those procedure names to the line where they are declared. Also write to the main index a similar list.
Parameters:
mainindex - I/O channel of index_main.html
Defined in:
tcldoc.tcl, line 535

write_index_footer

proc write_index_footer { dest }
Outputs a common footer for the various generated index files.
Parameters:
dest - I/O channel to write HTML footer
Defined in:
tcldoc.tcl, line 798

write_index_header

proc write_index_header { dest page_title index_line {page_header {}} }
Outputs a common header for the various generated index files.
Parameters:
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
Defined in:
tcldoc.tcl, line 767

write_index_master

proc write_index_master {  }
Writes the overall index.html that defines the frames. If an overview file was specified (with --overview) then have the index load the overview; otherwise just load index_main.html.
Defined in:
tcldoc.tcl, line 731

Overview | Index by: file name | procedure name | procedure call | annotation
File generated 2004-11-05 at 12:38.