--- ray/doc/man/man1/rtcontrib.1	2005/05/26 19:19:19	1.3
+++ ray/doc/man/man1/rtcontrib.1	2005/10/11 16:54:26	1.14
@@ -1,21 +1,30 @@
-.\" RCSid "$Id: rtcontrib.1,v 1.3 2005/05/26 19:19:19 greg Exp $"
+.\" RCSid "$Id: rtcontrib.1,v 1.14 2005/10/11 16:54:26 greg Exp $"
 .TH RTCONTRIB 1 5/25/05 RADIANCE
 .SH NAME
-rtcontrib - compute contributions in a RADIANCE scene
+rtcontrib - compute contribution coefficients in a RADIANCE scene
 .SH SYNOPSIS
 .B rtcontrib
 [
 .B "\-n nprocs"
 ][
+.B \-fo
+|
+.B \-r
+][
 .B "\-e expr"
 ][
 .B "\-f source"
 ][
-.B "\-o fspec"
+.B "\-o ospec"
 ][
 .B "\-b binv"
+][
+.B "\-bn nbins"
 ]
-.B "\-m mod .."
+{
+.B "\-m mod | \-M file"
+}
+..
 [
 .B $EVAR
 ]
@@ -26,6 +35,8 @@ rtcontrib - compute contributions in a RADIANCE scene
 rtrace options
 ]
 .B octree
+.br
+.B "rtcontrib [ options ] \-defaults"
 .SH DESCRIPTION
 .I Rtcontrib
 computes ray contributions (i.e., color coefficients)
@@ -35,6 +46,14 @@ settings.
 These modifiers are usually materials associated with
 light sources or sky domes, and must directly modify some geometric
 primitives to be considered in the output.
+A modifier list may also be read from a file using the
+.I \-M
+option.
+The RAYPATH environment variable determines directories to search for
+this file.
+(No search takes place if a file name begins with a '.', '/' or '~'
+character.)\0
+.PP
 The output of
 .I rtcontrib
 has many potential uses.
@@ -49,10 +68,20 @@ systems, such as luminaires, light pipes, and shading 
 .I Rtcontrib
 calls
 .I rtrace(1)
-to calculate the contributions for each input ray,
-and the output tallies are sent to one or more files according to the
+with the -oTW option to calculate the daughter ray
+contributions for each input ray, and the output tallies
+are sent to one or more destinations according to the given
 .I \-o
 specification.
+If a destination begins with an exclamation mark ('!'), then
+a pipe is opened to a command and data is sent to its standard input.
+Otherwise, the destination is treated as a file.
+An existing file of the same name will not be clobbered, unless the
+.I \-fo
+option is given.
+If instead the
+.I \-r
+option is specified, data recovery is attempted on existing files.
 If an output specification contains a "%s" format, this will be
 replaced by the modifier name.
 The
@@ -63,8 +92,16 @@ this will be applied to a "%d" format in the output fi
 specification if present.
 The actual bin number is computed at run time based on ray direction
 and surface intersection, as described below.
+If the number of bins is known in advance, it should be specified with the
+.I \-bn
+option, and this is critical for output files containing multiple values
+per record.
+Since bin numbers start from 0, the bin count is always equal to
+the last bin plus 1.
+Set the this value to 0 if the bin count is unknown (the default).
 The most recent
-.I \-b
+.I \-b,
+.I \-bn
 and
 .I \-o
 options to the left of each
@@ -96,12 +133,18 @@ The rules and predefined functions available for these
 described in the
 .I rcalc(1)
 man page.
+Unlike
+.I rcalc,
+.I rtcontrib
+will search the RADIANCE library directories for each file given in a
+.I \-f
+option.
 .PP
 If no
 .I \-o
 specification is given, results are written on the standard output in order
 of modifier (as given on the command line) then bin number.
-Concatenated data is also sent to a lone output file (i.e., an initial
+Concatenated data is also sent to a single destination (i.e., an initial
 .I \-o
 specification without formatting strings).
 If a "%s" format appears but no "%d" in the
@@ -176,8 +219,10 @@ pcomb -c 100 90 75 c_light1.pic -c 50 55 57 c_light2.p
 .PP
 To compute an array of illuminance contributions according to a Tregenza sky:
 .IP "" .2i
-rtcontrib -b tbin -o sky.dat -m skyglow -b 0 -o ground.dat -m groundglow
+rtcontrib -I+ -b tbin -o sky.dat -m skyglow -b 0 -o ground.dat -m groundglow
 @render.opt -f tregenza.cal scene.oct < test.dat
+.SH ENVIRONMENT
+RAYPATH		path to search for -f and -M files
 .SH AUTHOR
 Greg Ward
 .SH "SEE ALSO"