--- ray/doc/ray.1	2020/08/31 21:54:55	1.38
+++ ray/doc/ray.1	2023/11/15 18:28:09	1.41
@@ -1,8 +1,8 @@
-.\" RCSid "$Id: ray.1,v 1.38 2020/08/31 21:54:55 greg Exp $"
+.\" RCSid "$Id: ray.1,v 1.41 2023/11/15 18:28:09 greg Exp $"
 .\" Print using the -ms macro package
-.DA 8/31/2020
+.DA 11/13/2023
 .LP
-.tl """Copyright \(co 2020 Regents, University of California
+.tl """Copyright \(co 2023 Regents, University of California
 .sp 2
 .TL
 The
@@ -630,6 +630,8 @@ arguments have additional flexibility to specify the s
 Also, rather than roughness, specular power is used, which has no
 physical meaning other than larger numbers are equivalent to a smoother
 surface.
+Unlike other material types, total reflectance is the sum of
+diffuse and specular colors, and should be adjusted accordingly.
 .DS
 mod ashik2 id
 4+ ux uy uz funcfile transform
@@ -1192,6 +1194,73 @@ A section of text meant to depict a picture, perhaps u
 font such as hexbit4x1.fnt, calls for uniform spacing.
 Reasonable magnitudes for proportional spacing are
 between 0.1 (for tightly spaced characters) and 0.3 (for wide spacing).
+.LP
+.UL Spectrum
+.PP
+The spectrum primitive is the most basic type for introducing spectral
+color to a material.
+Since materials only provide RGB parameters, spectral patterns
+are the only way to superimpose wavelength-dependent behavior.
+.DS
+mod spectrum id
+0
+0
+5+ nmA nmB s1 s2 .. sN
+.DE
+The first two real arguments indicate the limits of the covered
+spectral range in nanometers.
+Subsequent real values correspond to multipliers in each wavelength band,
+where the first band goes from nmA to nmA+(nmB-nmA)/N, and N is the
+number of bands (i.e., the number of real arguments minus 2).
+The nmA wavelength may be greater or less than the nmB wavelength,
+but they may not be equal, and their ordering must correspond to
+the ordering of the spectral values.
+A minimum of 3 values must be given, which would act
+more or less the same as a constant RGB multiplier.
+As with RGB values, spectral quantities normally range between 0
+and 1 at each wavelength, or average to 1.0 against a standard
+sensitivity functions such as V(lambda).
+The best results obtain when the spectral range and number
+of samples match rendering options, though resampling will handle
+any differences, zero-filling wavelenths outside the nmA to nmB
+range.
+A warning will be issued if the given wavelength range does not
+adequately cover the visible spectrum.
+.LP
+.UL Specfile
+.PP
+The specfile primitive is equivalent to the spectrum type, but
+the wavelength range and values are contained in a 1-dimensional
+data file.
+This may be a more convenient way to specify a spectral color,
+especially one corresponding to a standard illuminant such as D65
+or a library of measured spectra.
+.DS
+mod specfile id
+1 datafile
+0
+0
+.DE
+As with the spectrum type, rendering wavelengths outside the defined
+range will be zero-filled.
+Unlike the spectrum type, the file may contain non-uniform samples.
+.LP
+.UL Specfunc
+.PP
+The specfunc primitive offers dynamic control over a spectral
+pattern, similar to the colorfunc type.
+.DS
+mod specfunc id
+2+ sval funcfile transform
+0
+2+ nmA nmB A3 ..
+.DE
+Like the spectrum primitive, the wavelength range is specified
+in the first two real arguments, and additional real values are
+accessible to the sval function.
+This function is fed a wavelenth sample
+between nmA and nmB as its only argument,
+and it returns the corresponding spectral intensity.
 .NH 3
 Mixtures
 .PP
@@ -1593,6 +1662,14 @@ the Ecole Polytechnique Federale de Lausanne (EPFL Uni
 in Lausanne, Switzerland.
 .NH 1
 References
+.LP
+Ward, Gregory J., Bruno Bueno, David Geisler-Moroder, 
+Lars O. Grobe, Jacob C. Jonsson, Eleanor
+S. Lee, Taoning Wang, Helen Rose Wilson,
+``Daylight Simulation Workflows Incorporating
+Measured Bidirectional Scattering Distribution Functions,''
+.I "Energy & Buildings",
+Vol. 259, No. 111890, 2022.
 .LP
 Wang, Taoning, Gregory Ward, Eleanor Lee,
 ``Efficient modeling of optically-complex, non-coplanar