'\" t .TH CATM 1 "November 1994" .SH NAME catm \- concatenate, merge and expand files .SH SYNOPSIS .B catm [ -f .I fieldsname ] [ -s .I char ] [-e .I end-of-page-text ] .I listfile .I file2 .I file3 .br or .br .B catm [ -f .I fieldsname ] [ -s .I char ] [-e .I end-of-page-text ] .I listfile -o .I file-once -r .I file3 .I file4 .br or .br .B catm [ -f .I fieldsname ] [ -s .I char ] [-e .I end-of-page-text ] .I listfile -o .I file-once -r .I file3 .I file4 -o .I file2-once .SH AVAILABILITY .B catm is provided with the .I Quikscript document formatting system. .I Quikscript is available via anonymous ftp from ftp://ftp.adfa.edu.au/pub/postscript/qsdir/ .SH DESCRIPTION .B catm will read the first file .RI ( listfile ) and repeatedly copy the remaining files to standard output, performing substitutions based on information read from the first. .I listfile is the field values file, and will contain the names of .I fields and sets of values for them. The files repeatedly copied will be searched for references to the field names in <> brackets, and such references to a field will be replaced by the current value of this field as determined from .IR listfile . Redirection of this output to a file or a pipe is most common. The .B -f option, which must precede the "listfile", indicates that the field-names are defined in a separate file. This allows the "listfile" to contain only field values, without needing the field names to be defined at the top with the first set of fields. This file can also contain the "END=" directive described below on a second line, further enabling field content to be completely separated from "catm" processing instructions. Note that "END" is a reserved field name if the "-f" option is not used. The .B -s option allows the field separator character to be changed from the Tab character. This only has effect if the field file is organized with multiple field values per line. While copying the files: If the text string .I %include file-name% is encountered, the file named will be included in the output at that point. If the text string .I %DATE% is encountered, the current date will be substituted. These are referred to below as .B INCLUDE .BR PROCESSING . If the text string .RI < text > is encountered, then it will be replaced by the current value associated with the name .I text found from the first file .BR ( listfile ) in the above examples. This is referred to below as .B FIELD .BR PROCESSING . If the text .I %DM,name:string:% is encountered, it will be taken as an defining a macro. Wherever .I %M,name% is subsequently found, the text in .I string will be substituted. This is referred to below as .B MACRO .BR PROCESSING . .SH COMMAND ARGUMENT PROCESSING The list of arguments is interpreted as filenames, except for the flags .B -o meaning output once, and .B -r meaning output repeatedly. The first file is read and interpreted as a set of field definitions that will be applied to other files (the ones to be repeatedly output). If a .B -o is encountered after the first file, it indicates that the following files are to be output directly with only include processing and macro processing being performed. If a .B -r is encountered after the first file, it indicates that the following files are to be repeatedly output, in turn using each set of field values from the first file. On each occasion, full include and macro processing is performed. If neither .B -o nor .B -r are present, all files after the first are repeatedly output with field, macro and include processing. .SH FIELD PROCESSING Files for repeated processing are read in turn and copied to standard output. If a string .RI < text > is encountered in the file, where .I text is a field-name defined in the first file or in a .B -f field-name file, the value of the field is substituted for the string. This process of substituting and copying all the remaining files is repeated for each of the groups of field definitions in the first file. The simplest way to set up the fields file is to provide on the first line the names of the fields, Tab separated. Subsequent lines will then contain the values of the fields for the next version of the document being generated. If the .B -f option is used, then the file specified after .B -f will be read seeking the field names, rather than expecting them at the head of the field values file. An alternative layout of the field values file is as follows: .TS center; l lw(10c). END=text T{ Defines what should separate the documents generated by each group of fields. If omitted, the default text will be \fI%NP%%PS%\enQSdict begin PrintLoop\en\fP T} text1=text text2=text \. \. \. T{ Occurrence of <\fItext1\fP> in a file will be replaced by the substitute text given here after the \fI=\fP. Within the text, \en means newline, \et means tab, \e before end of line means include the next line with this substitute text. T} NEXT T{ Ends the field definitions for the first document to be generated. The file arguments will be processed using these fields, then the fields will be emptied before the next set of fields is read. T} text1=text \. \. \. T{ End-of-file is equivalent to a \fBNEXT\fP T} .TE Under this scheme, values for the fields must be in the same order for each document, though some may be omitted. The occurrence of the last field will be sufficient to cause that document to be generated, without the need for an explicit NEXT. After the first NEXT, lines that lack a textn= prelude are taken as specifying a value for the next field name. If the .B -f option is used to define field names, the .B -f file will contain the names, separated by tabs or new-line characters, and possibly containing the END= directive. The file of fields will contain values for the fields, either tab or new-line separated, in the same order as the field names. When a reference to a .I < fieldname > is found in a document to be output, the current replacement text is treated as if it is part of the input document. As this replacement text is output, it is scanned for any macro references, include directives, or other field references which are processed as they are encountered. .SH INCLUDE PROCESSING If the string .I %include name% is found at the beginning of a line, the name is interpreted as a file name; reading of the original file is suspended, and the new file is inserted in the output stream. A file being included can itself contain .I %include newname% instructions, and such new files will be inserted appropriately. Calls to include files can be nested to any depth. (Including a file recursively will cause an infinite loop.) A file-name is interpreted relative to the file from which it was called. Names beginning with \fB..\fP are interpreted as being in a higher level directory. A string .I %DATE% within a file will be replaced by the current local date. .SH MACRO PROCESSING Within a file that is to be copied to output, macros can be defined using the form .IR %DM,name:string:% , and such strings will not immediately be copied to the output. These set up text substitutions that will apply to the remainder of the files as they are copied to output. Such macros can be invoked with .IR %M,name% , so that this text will be replaced by the string in the definition. Invocation is recursive, that is the replacement text is not simply copied directly to standard output, but instead is processed as the input stream. Within this replacement text may be other macro invocations .RI ( %M,othername% ), new macro definitions, or .IR %include directives. (A macro cannot be redefined within its own body; our simple syntax will not allow colons to appear in the .I string part of a definition). .SH EXAMPLES The first file (fields) might look like NAME \t PERS \t ADDR1 \t ADDR2 \t ADDR3 Mr H. Bloggs \t Henry \t 360 Hindmarsh Dr \t Phillip, ACT 2616 \t Australia Ms R. McManus \t Rosemary \t 19 McWilliam Cres \t Florey, WA 6517 \t Mr GA Spence \t Mr Spence \t 40 Plenty Ave \t Lower Hutt \t New Zealand Mrs P Thomas \t Penni \t Computer Science \t ADFA \t Campbell, ACT 2600 and the third file (letter) might look like %include ../pscode/letter.hd.qs% %DATE% Dear %FI%According to my records, you have not completed the ... The output pages could be generated with Qs layout using catm fields -o Qs -r letter | lpr -Plaser so that the Quikscript file (Qs) will be copied once at the start, followed by four copies of the letter, each tailored to a name and address given in the fields file. In this case, the output generated by this .I catm command will be: Quikscript file letter.hd.qs file today's date Henry Bloggs 360 Hindmarsh Dr Phillip, ACT 2616 Australia Dear Henry %FI%According to my records, you have not completed the ... letter.hd.qs file today's date Rosemary McManus 19 McWilliam Cres Florey, ACT 2617 Dear Rosemary %FI%According to my records, you have not completed the ... letter.hd.qs file today's date GA Spence 40 Plenty Ave . . . Alternatively, the field values file (fields) might look like NAME=Henry Bloggs PERS=Henry ADDR1=360 Hindmarsh Dr ADDR2=Phillip, ACT 2616 ADDR3=Australia NEXT Rosemary McManus Rosemary 19 McWilliam Cres Florey, ACT 2617 GA Spence Mr Spence 40 Plenty Ave Lower Hutt New Zealand Penni Thomas Penni Dept Computer Science ADFA Campbell, ACT 2600 .SH SEE ALSO .BR catex (1), .B Quikscript user documentation. .SH AUTHOR Copyright: Graham Freeman, November 1994, October 2004.