.BG
.VE $Header: /usr/s/current/s/.help/RCS/REPORT,v 1.3 85/08/09 15:01:41 rab Exp $
.FN REPORT
.TL
REPORT: Report writing facility
.CS
!S REPORT [\-e] input output     # UNIX cmd - batch
!S REPORT [\-e] input >output    # UNIX command
!S REPORT [\-e] <input >output   # UNIX command
.PP
.AG input
the name of a file containing the text of the report,
along with `troff' macros and embedded S commands.
The S commands are executed and their printed results
replace them in the body of the input file.
The S commands are surrounded in the text by braces
( `{' and `}' ).
Output lines from the S command have leading blanks
and all quote characters (") removed.
If the S expressions are surrounded by
doubled braces (`{{' and `}}'), the printed S output is
left alone.
.AG output
the name of a file which will receive all of the output from the
run.
.PP
If the flag `\-e' is given to `REPORT', then single or double
braces beginning S expressions must be preceded by
a backslash character ( `\\{' or `\\{{' ).
This allows the input file to contain braces which are not
interpreted by `REPORT'; in particular, the UNIX
`eqn' preprocessor uses braces for grouping.
.IP Warning:
execution of `REPORT' in batch mode begins immediately after the command
is typed.
Processes running in batch are counted toward the total number
of processes any one user is allowed.
Running several versions of S (either batch or interactive)
at the same time can cause you to exceed the process limit,
and abort all of the runs.
.EX
.ft 1
Suppose the input file named `myinput' looks like this:


 .PP
 This is a test report generated by S expressions.
 For example, the mean winnings of New Jersey Lottery players
 was ${ round(mean(lottery.payoff),2)}.
 Another thing, there were { len(lottery.payoff)}
 players during the time period.
 .PP
 How about a stem-and-leaf of the winnings?
 .DS
 {{stem(lottery.payoff)}}
 .DE
 Well, this is it. { "Guess I'll quit now." }
 .PP
 What the heck, I'd better include an in-line table to make
 people happy.  For example, the first hunk of the iris data
 looks like:
 {tbl(iris[1:5,,1],file="iris.tbl",head="A Hunk of Iris Data")
 !tbl iris.tbl >iris.out}
 .so iris.out
 So here it is, embedded right in the middle of the text I'm
 now composing.  Pretty neat, huh?

The report-writing S run can be invoked in batch with
.NF
.ft 3
    S REPORT myinput myoutput
.ft 1
.PP
Once the batch run is complete, the output file can be processed
with the Unix command line:
.NF
.ft 3
    nroff \-ms myoutput
.ft 1
.PP
to produce the following document:
(The command
.br
`S REPORT myinput | nroff \-ms'
.br
would produce the same result.)
.NF
.ft CW
.ps -3
.vs -3

      This is a test report generated by S expressions.   For
 example, the mean winnings of New Jersey Lottery players was
 $290.36.  Another thing, there were 254 players  during  the
 time period.
 
      How about a stem-and-leaf of the winnings?

      N = 254   Median = 270.25
      Quartiles = 194, 365
      
      Decimal point is 2 places to the right of the colon
      
         0 : 8
         1 : 000011122233333333333344444
         1 : 55555566666677777778888888899999999999
         2 : 0000000111111111111222222233333333444444444
         2 : 555556666666666777778889999999999999999
         3 : 000000001111112222333333333444
         3 : 55555555666667777777888888899999999
         4 : 0122234
         4 : 55555678888889
         5 : 111111134
         5 : 555667
         6 : 44
         6 : 7
      
      High: 756.0 869.5
      
 Well, this is it. Guess I'll quit now.
 
      What the heck, I'd better include an in-line  table  to
 make  people happy.  For example, the first hunk of the iris
 data looks like:
 
 
                   _______________________
                   |_A_Hunk_of_Iris_Data__|
                   |5.1 | 3.5 | 1.4 | 0.2 |
                   |4.9 | 3.0 | 1.4 | 0.2 |
                   |4.7 | 3.2 | 1.3 | 0.2 |
                   |4.6 | 3.1 | 1.5 | 0.2 |
                   |5.0 | 3.6 | 1.4 | 0.2 |
                   |____|_____|_____|_____|
 
 So here it is, embedded right in the middle of the text  I'm
 now composing.  Pretty neat, huh?

.ps +3
.vs +3
.PP
A few comments are in order concerning the example.  The 
table is produced by two separate steps.  First, the function
`tbl' writes an ascii file.
Then, the Unix `tbl' command reads that file and produces a file
suitable for `troff'.
The reason for the latter step is that the `tbl' command will
not follow `.so' lines in a document.
.PP
S expressions enclosed in doubled braces should be processed in
`troff' with a constant-width font to preserve spacing.
.PP
Plotted output can be included in a phototypeset
report by means of the `pic'
device driver and Unix `pic' and `troff' commands.
Typical embedded S commands might look like this:
.NF
.ft 3
 { pic; plot(my.x, my.y); printer
 !mv pic.out fig.1 }
 .PS <fig.1
.PP
This sequence invokes the `pic' device driver, produces a plot,
and then invokes the `printer' device driver to cause `pic' to
terminate.  Then, the output file is renamed via the Unix
`mv' command and called `fig.1'.
Sequences such as this can appear many times in the document
as long as the `pic.out' files are all given different names.
.PP
When the `S report' phase is through, the output file
is passed through the Unix `pic' command prior to `troff':
.NF
.ft 3
    pic myoutput |troff \-ms
.KW utilities
.KW UNIX
.KW reports
.WR
