188 lines
3.9 KiB
Groff
188 lines
3.9 KiB
Groff
.TH report "" "" "/rdb Command"
|
|
.PC "Write reports using a form and a table"
|
|
\fBreport \fIform \fB< \fItableorlist\fR
|
|
.PP
|
|
The command
|
|
.B report
|
|
produces reports, form letters, mailing labels, invoices,
|
|
and so forth, for each row in
|
|
.IR tableorlist ,
|
|
following the template within file
|
|
.IR form .
|
|
.PP
|
|
You must use a text editor to fill out
|
|
.I form
|
|
to determine how the form will appear.
|
|
Insert column names from
|
|
.I tableorlist
|
|
between angle brackets (< >)
|
|
where you want the data to appear within the report.
|
|
.PP
|
|
You can even call shell commands from within a form,
|
|
pass them data from
|
|
.IR tableorlist ,
|
|
print their output within your formatted form.
|
|
This is a powerful extension to COHERENT shell programming.
|
|
.PP
|
|
.B report
|
|
mostly replaces the older commands
|
|
.B label
|
|
and
|
|
.BR letter .
|
|
These commands are still part of
|
|
.BR /rdb ,
|
|
in part for compatibility with older versions, and in part as examples
|
|
of shell programming.
|
|
.SH "Form Syntax"
|
|
The following describes the format of a form:
|
|
.IP "\fIregular text\fR"
|
|
.B form
|
|
prints any characters in your form that do not match the symbols
|
|
shown below.
|
|
.IP "\fI<column-name>\fR"
|
|
Angle brackets indicate that data from
|
|
.I "column-name"
|
|
in the current row of
|
|
.I tableorlist
|
|
should be inserted in place of the column name.
|
|
.IP "\fI<!command!>\fR"
|
|
Angle brackets and exclamation points indicate that the shell is to execute
|
|
.IR command .
|
|
Any output from
|
|
.I command
|
|
appears at this point in the report.
|
|
.IP "\fI<!cmd <col>!>\fR"
|
|
This is an insertion within a command.
|
|
The data from column
|
|
.I col
|
|
in the current row of
|
|
.I tableorlist
|
|
are passed to
|
|
.IR cmd .
|
|
This passes the contents of
|
|
.I col
|
|
as an argument to
|
|
.IR command .
|
|
The output of
|
|
.I command
|
|
then replaces this entry within the form.
|
|
.PP
|
|
If
|
|
.B report
|
|
does not recognize a column name, it prints
|
|
.I "<column-name>"
|
|
as if it were normal text.
|
|
This allows you to use the angle brackets as literal characters within your
|
|
form, if you wish.
|
|
It also helps you debug your form:
|
|
if the data from the table are not replacing
|
|
.IR "<column-name>" ,
|
|
then
|
|
.I "column-name"
|
|
does not exactly match the column name in the table.
|
|
Check for spelling errors, upper- and lower-case discrepancies,
|
|
embedded blanks, and nonprinting characters.
|
|
.SH Example
|
|
Consider table
|
|
.BR maillist ,
|
|
as follows:
|
|
.DM
|
|
Name Ronald McDonald
|
|
Company McDonald's
|
|
Street 123 Mac Attack
|
|
City Memphis
|
|
State TENN
|
|
ZIP 30000
|
|
Phone (111) 222-3333
|
|
.DE
|
|
.DM
|
|
Name Chiquita Banana
|
|
Company United Brands
|
|
Street Uno Avenido de la Reforma
|
|
City San Jose
|
|
State Costa Rica
|
|
ZIP 123456789
|
|
Phone 1234
|
|
.DE
|
|
.PP
|
|
You could use an editor to develop a form like the following:
|
|
.DM
|
|
<Name>
|
|
<Company>
|
|
<Street>
|
|
< City >, <State> <ZIP>
|
|
.DE
|
|
.DM
|
|
Hi < Name >:
|
|
.sp \n(pDu
|
|
The date and time is <!date!>
|
|
.sp \n(pDu
|
|
We are also sending this letter to:
|
|
.sp \n(pDu
|
|
<! column Name City < mailtable | row 'Name != "<Name>"' | justify !>
|
|
Bye <! echo <Name> !>
|
|
.DE
|
|
.PP
|
|
Note that we have used all three types of inserts:
|
|
column name, command, and command insert.
|
|
Now with these two files ready, you only need type
|
|
.DM
|
|
report form < maillist
|
|
.DE
|
|
.PP
|
|
to see the following output:
|
|
.B1
|
|
Ronald McDonald
|
|
McDonald's
|
|
123 Mac Attack
|
|
Memphis, TENN 30000
|
|
.sp
|
|
Hi Ronald McDonald:
|
|
.sp \n(pDu
|
|
The date and time is Wed Aug 19 01:58:19 PST 1983
|
|
.sp \n(pDu
|
|
We are also sending this letter to:
|
|
.sp
|
|
Name City
|
|
--------------- -------
|
|
Chiquita Banana San Jose
|
|
.sp \n(pDu
|
|
Bye Ronald McDonald
|
|
.B2
|
|
.PP
|
|
.B1
|
|
Chiquita Banana
|
|
United Brands
|
|
Uno Avenido de la Reforma
|
|
San Jose, Costa Rica 123456789
|
|
.sp \n(pDu
|
|
Hi Chiquita Banana:
|
|
.sp \n(pDu
|
|
The date and time is Wed Aug 19 01:58:40 PST 1983
|
|
.sp \n(pDu
|
|
We are also sending this letter to:
|
|
.sp \n(pDu
|
|
Name City
|
|
--------------- -------
|
|
Ronald McDonald Memphis
|
|
.sp \n(pDu
|
|
Bye Chiquita Banana
|
|
.B2
|
|
.PP
|
|
Some users have noted that the shell escape places an
|
|
extra line in the output.
|
|
If you don't want the extra line say something like:
|
|
.DM
|
|
<! echo -n `date` !>
|
|
.DE
|
|
.SH "See Also"
|
|
.B
|
|
label,
|
|
letter
|
|
.R
|
|
.br
|
|
COHERENT Lexicon:
|
|
.B
|
|
echo
|
|
.R
|