--- ray/doc/man/man1/rcollate.1	2019/11/11 18:38:41	1.12
+++ ray/doc/man/man1/rcollate.1	2024/01/25 19:25:50	1.18
@@ -1,7 +1,7 @@
-.\" RCSid "$Id: rcollate.1,v 1.12 2019/11/11 18:38:41 greg Exp $"
-.TH RCOLLATE 1 7/8/97 RADIANCE
+.\" RCSid "$Id: rcollate.1,v 1.18 2024/01/25 19:25:50 greg Exp $"
+.TH RCOLLATE 1 9/5/2013 RADIANCE
 .SH NAME
-rcollate - resize or transpose matrix data
+rcollate - resize or re-order matrix data
 .SH SYNOPSIS
 .B rcollate
 [
@@ -9,8 +9,10 @@ rcollate - resize or transpose matrix data
 ][
 .B \-w
 ][
-.B \-f[afdb][N]
+.B \-c
 ][
+.B \-f{a|f|d|b}[N]
+][
 .B \-t
 ][
 .B "\-ic in_col"
@@ -61,6 +63,16 @@ The
 .I \-w
 option turns off non-fatal warning messages, such as unexpected EOD.
 .PP
+Normally,
+.I rcollate
+detects whether any transformation is actually taking place, and will
+reproduce the data verbatim if the input size and shape should be unaltered.
+The
+.I \-c
+opiton forces the operation to proceed, even if it appears to be a no-op,
+which can be useful to correct a misshapen input matrix or check that
+the data is the proper size and formatted correctly (in the case of ASCII input).
+.PP
 The input format is assumed to be ASCII, with three white-space separated words
 (typically numbers) in each record.
 A different input format may be specified with the
@@ -89,8 +101,8 @@ and
 would all be equivalent.
 Note that the lack of row separators in binary files means that
 .I rcollate
-does not actually do anything for binary files unless the transpose
-option is given, also.
+does not actually do anything for binary files unless the data is being
+re-ordered.
 .PP
 If an input header is present, it may contain the format, number of components
 and matrix dimensions.
@@ -101,32 +113,32 @@ and
 .I \-f
 options are not required, but will be checked against the header
 information if provided.
+An exception is made for
+.I \-fbN
+where N>1, when no checks are made against the header,
+and the given length is assumed
+to be the exact size (in bytes) of each data record.
 .PP
 The transpose option,
 .I \-t
 swaps rows and columns on the input.
-For binary files, the user must specify at least one input or output
-dimension to define the matrix size.
+For binary files with no header information, the user must
+specify at least one input or output dimension to define the matrix size.
 For ASCII files,
 .I rcollate
 will automatically determine the number of columns based on the
 position of the first EOL (end-of-line) character, and the number
 of rows based on the total count of records in the file.
 The user may override these determinations, allowing the matrix to
-be resized as well as transposed.
-If input and output dimensions are given, the number of input rows
-must equal the number of output columns,
+be resized or re-ordered as well as transposed.
+If input and output dimensions are given and there is no block re-ordering,
+the number of input rows must equal the number of output columns,
 and the number of input columns must equal the number of output rows.
-For large transpose operations on Unix systems, it is most efficient
-to specify the input file on the command line, rather than reading
-from the standard input, since
-.I rcollate
-can map the file directly into virtual memory.
 If the
 .I \-o
 option is also given with multiple block levels, the transpose operation
-will logically precede the reblocking operation, regardless of the order
-they are given on the command line.
+will logically precede the re-ordering operation, regardless of their
+position on the command line.
 .SH EXAMPLES
 To change put 8760 color triplets per row in a matrix with no header:
 .IP "" .2i
@@ -148,6 +160,12 @@ rcollate -o 64x64X32x32 s-c_bsdf.mtx | rmtxop -fc - > 
 .SH AUTHOR
 Greg Ward
 .SH NOTES
+For large transpose or re-ordering operations on Unix systems,
+it is most efficient to specify the input file on the command line,
+rather than reading from the standard input, since
+.I rcollate
+can map the file directly into virtual memory.
+.PP
 The
 .I rcollate
 command is rather inflexible when it comes to output field and record
@@ -158,9 +176,9 @@ between words and tabs as record separators on output.
 Output row separtors will always be an EOL, which may differ between systems.
 .PP
 If no options are given on the command line, or a binary file is specified
-without a transpose,
+without a transpose or re-ordering,
 .I rcollate
 issues a warning and simply copies its input to its standard output.
 .SH "SEE ALSO"
-cnt(1), histo(1), neaten(1), rcalc(1), rlam(1), rmtxop(1), 
-rsplit(1), tabfunc(1), total(1)
+cnt(1), histo(1), neaten(1), rcalc(1), rcomb(1), rcrop(1), rlam(1),
+rsensor(1), rmtxop(1), rsplit(1), tabfunc(1), total(1)