                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================























                                   TclVSrpt                            
                         Tcl Very Simple Report Writer                 

                                  Version 1.1                          
                                Steven B. Wahl                         
                               October 18, 1995                        






       Introduction                                                    
       ____________                                                    

       TclVSrpt  (TCL  Very Simple RePorT writer) is a small but powerful
       set  of  Tcl  procedures  for  easily creating Postscript or ASCII
       reports  from  Tcl  applications.   TclVSrpt  is written utilizing
       vanilla  Tcl  7.3  /  7.4  /  7.5  commands and requires no C code
       extensions  or  patches  to  the  Tcl  interpreter.   As a result,
       TclVSrpt is suitable for use in any Tcl environment.            

       TclVSrpt   is   part  of  the  TclVS  family  of  Tcl  application
       development  tools.   Also of this family are TclVSdb, a Tcl 7.3 /
       7.4  /  7.5  multi-user,  multi-table-row-column oriented database
       facility  that  maps fields naturally into Tcl array variables and
       Tcl  lists.   Another  TclVS  package  is TkVSform, a Tk 4.0 / 4.1
       forms  package  for  quickly,  clearly,  consistently, and tersely
       defining  application  user interfaces.  These three packages work



      _________________________________________________________________
       TclVSrpt v1.0                Page 1                    User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



       well together, but each may be used independently.              

       Features                                                        
       ________                                                        

       *  Same command interface for ASCII text or Postscript reports
          (simple switch setting).                                     
       *  14 native paper sizes plus any custom paper sizing.          
       *  Portrait or landscape page orientations.                     
       *  Extensive page header, page footer, and page numbering options.
       *  Page margins (top, bottom, left, right) may be set
          individually.                                                
       *  Unlimited text appearance style definitions allowed.         
       *  11 standard Postscript fonts supported.                      
       *  User-defined (preloaded) Postscript fonts supported.         
       *  Encapsulated Postscript (EPSF) image file inclusion supported.
       *  Standard, ISOLatin1, Diacritic, and user-defined Postscript
          encodings supported.                                         
       *  Left, centered, right and concurrent left-right justification
          options.                                                     
       *  Font selection, font size, bolding, italics, and underlining
          options.                                                     
       *  Line leading, and line wrapping options available.           
       *  Initial line indentation, line prefix, wrap suffix, and wrap
          indentation controls.                                        
       *  Unlimited tab settings per style definition; tabs may be left,
          centered, or right aligned.                                  
       *  Tab resolution may be set to nearest tab or absolute
          tabination.                                                  
       *  Automatic, conditional, or unconditional page ejection.      
       *  Output may be directed to file or printer with optional
          multiple copies.                                             
       *  Support for pass-through inclusion of files or unformatted
          text to the document sensitive to document type.             
       *  All functionality presented in 12 easy to use Tcl procedures.
       *  All procedure arguments are given with a dashed option names
          for clarity and maintainability.                             

       Current Limitations                                             
       _______ ___________                                             

       *  No graphics drawing or image generation operators.           
       *  No kerning support.                                          
       *  No multi-column support.                                     
       *  Performance is not dazzling.                                 








      _________________________________________________________________
       TclVSrpt v1.0                Page 2                    User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



       Organization                                                    
       ____________                                                    

       "TclVSrpt.tcl"   contains   the   twelve   user-callable  TclVSrpt
       procedures  plus  a  number  of  internal utility procedures.  All
       TclVSrpt   procedure   names   are  prefixed  with  rpt  for  easy
       identification.   Internal  utility  procedures  are prefixed with
       rptu.  A  single global array variable, RPT is created by TclVSrpt
       during document generation and is removed when the report is done.
       RPT    should   be   considered   an   opaque   variable   without
       user-modifiable  elements.   Tinkering  with  RPT may cause damage
       such  that TclVSrpt will behave abnormally or to cease to function
       altogether.   All  user and application interaction is intended to
       take place through the ten public procedures.                   

       The  public  TclVSprt  procedures  (and  an  approximate  order of
       execution) are:                                                 

            rptInitialize                                              
                (Initialize package, set to ASCII or Postscript output)
            rptDefPaper                                                
                (Define paper size, orientation, and margins)          
            rptDefPage                                                 
                (Define page headers, page footers, and page numbering)
            rptDefStyle                                                
                (Assign font and line appearance options to a mnemonic na
            rptSetStyle                                                
                (Apply font and line appearance options associated with a
            rptInclude                                                 
                (pass the contents of a file to document without formatin
            rptInsert                                                  
                (pass the contents of a string to document without format
            rptAddText                                                 
                (Add from single character to multiple lines to the docum
            rptAddLine                                                 
                (Add a complete line of text to the document)          
            rptNewLine                                                 
                (Flush current line, add zero or more empty lines to docu
            rptNewPage                                                 
                (Conditionally or unconditionally start on new page)   
            rptDone                                                    
                (Document complete, send it to a file and / or a printer)
                                                                       
       Command  or style options that are only appropriate for Postscript
       report  generation  are  politely  and  silently  ignored  if  the
       document type is set to "ASCII".                                






      _________________________________________________________________
       TclVSrpt v1.0                Page 3                    User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



       TclVSrpt Procedure Command Arguments                            
       ________ _________ _______ _________                            

       All  TclVSrpt  procedures  take  arguments  that  are positionally
       independent  and  rely on a dashed option name followed by zero or
       more  value  settings.   The option names are case insensitive and
       were   selected  to  be  relatively  clear  and  self-documenting.
       Generally,   when  an  option  is  given  a  value  with  embedded
       whitespace,  that option value should be quoted.  Likewise, option
       arguments  with  special  quoting,  escape  characters, braces and
       brackets  should be protected with a leading backslash (\) if they
       are  intended  to  be  interpreted  literally. Examples of command
       arguments are:                                                  

            rptDefStyle -name body -font Times -align justify          
            rptAddLine This is a line of \"independent\" arguments.    
            rptDefStyle -NAME Heading -GAP .5I -FONT HELVETICA -SIZE \ 
                18P -ALIGN LEFT                                        
            rptAddLine "This line is defined as a single argument."    

       Size and Position Values                                        
       ____ ___ ________ ______                                        

       Many  of  the  TclVSrpt commands require either a size or location
       value  to  be  given.   For  a location value, the paper origin is
       defined  as  the  lower-left  corner with Y-axis values increasing
       towards  the  top of the page and X-axis values increasing towards
       the  right  of  the  page.  The  default units used by TclVSrpt is
       points  (1/72  inch).  Both  real numbers or integers may be given
       for  any  size  or  location  option  value.  Any isolated numeric
       value   given  to  a  command  will  be  interpreted  as  a  point
       specification.   However,  there  are built-in conversion suffixes
       for  specifying  values in inches (i) and centimeters (c).  That a
       value  is  intended  to  be in points may be clear by adding a (p)
       suffix  [tip of the hat to Gerald Rosenberg's tkReport].  Examples
       of size and location value specification are:                   

            rptDefStyle -name Comment -size 10p -font Times -italic    
            rptDefStyle -name Code -font Courier -size .1i -gap .05i   
            rptDefStyle -name Heading -gap 2.2c -size 1c -font AvantGarde

       Defining and Setting Styles                                     
       ________ ___ _______ ______                                     

       An  unlimited  number of fonting and line appearance styles may be
       defined  within TclVSrpt.  A style is a mnemonic name for a set of
       font   and   line  appearance  options.   Defining  a  style  with
       "rptDefStyle"  only  captures  the style options and value setting
       for  possible use later. To put a style into effect, you must call
       "rptSetStyle"  with the mnemonic name earlier assigned to a set of
       style options.                                                  



      _________________________________________________________________
       TclVSrpt v1.0                Page 4                    User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================




       A  style  may  be  changed both between lines of text and within a
       line  of text.  Caution should be exercised if changing font sizes
       or  line gapping with a style change within a line as only the gap
       and  font  size  of the style in effect at line transition is used
       to determine the vertical placement of the line.                

       There  are  sixteen possible font and line appearance options that
       may be set when defining a style:                               

       *  Font             The name of the Postscript font to use      
       *  Size             The size of the Postscript font (normally
                           given in points)                            
       *  Bold             Make the Postscript font bolded             
       *  Italic           Make the Postscript font italic             
       *  Underline        Underline each non-blank character          
       *  Gap              Set the distance between lines of text      
       *  Alignment        Set text alignment to left-justified,
                           center-justified, right-justified, or
                           concurrent left and right justification     
       *  Left Indent      Set style's left margin inward from page's
                           left margin                                 
       *  Right Indent     Set style's right margin inward from page's
                           right margin                                
       *  Line Indent      Left indentation of first non-wrapped line of
                           text in a paragraph                         
       *  Wrap Indent      Left indentation of wrapped lines of text in
                           a paragraph                                 
       *  Line Prefix      Prefix characters for non-wrapped lines of
                           text                                        
       *  Wrap Characters  Suffix characters for the end of wrapped
                           lines of text                               
       *  Wrap / No wrap   Turn on /off line wrapping when words would
                           exceed right margin                         
       *  Tabs             List of tab stop locations and alignments
                           (left, centered, right)                     
       *  Tab Style        Whether a tab will resolve to the nearest tab
                           stop or the next stop                       

       Not  all options for a style need to be set when defining a style.
       A  reasonable  set of default values are assumed for style options
       that  are  not  explicitly set.  One thing to bear in mind is that
       style  options  do  not  carry  forward after a style has changed.
       Each  style  option  required  to  be in place when a style change
       occurs must be explicitly set for that style.                   






      _________________________________________________________________
       TclVSrpt v1.0                Page 5                    User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



       One  interesting  and  reasonable  set  of style defaults are with
       tabs.  If  tabs  stops  are  not  set  for  a style, then a set of
       left-aligned  tab stops every 1/2 inch are assumed, with a default
       tab style of resolving to the nearest tab stop.                 

       Styles  may  be  recycled.   There is no prohibition on completely
       redefining the style options for a previously defined style name. 

       Four styles are automatically created by TclVSrpt:              

       *  default          style assumed if no style has been set for
                           document                                    
       *  pageheader       style used by the optional top line of the
                           page header                                 
       *  pagesubheader    style used by the optional second line of the
                           page header                                 
       *  pagefooter       style used by the option page footer        


       Fonts                                                           
       _____                                                           

       Eleven  standard Postscript fonts are supported by TclVSrpt.  Font
       names,  font sizing, bolding, and italic style options are ignored
       within  ASCII documents, but underlining and interline gap setting
       options  are  honored.   The  eleven  Postscript font name and the
       nominal expression of the font name to "rptDefStyle" are:       

       *  AvantGarde       (avant)                                     
       *  Bookman          (book)                                      
       *  Courier          (cour)                                      
       *  Helvetica        (helvetica)                                 
       *  Helvetica-Narrow (helvetica-n)                               
       *  NewCenturySchlbk (newc)                                      
       *  Palatino         (pala)                                      
       *  Symbol           (symb)                                      
       *  Times            (time)                                      
       *  ZapfChancery     (zapfc)                                     
       *  ZapfDinbats      (zapfd)                                     

       As  TclVSrpt  performs  pagination,  line  justification  and line
       wrapping  itself,  it  needs  to know the width of each Postscript
       character.   This  is  done  by  examining the corresponding Adobe
       Font  Metrics  file (.afm) found in "$env(TCL_LIBRARY)/TclVS/afm".
       The  .afm  files for the standard 11 Postscript fonts are supplied
       and installed with TclVSrpt.  The file,
       "$env(TCL_LIBRARY)/TclVS/afm/fontmap"  is consulted by TclVSrpt at
       start-up  time  to map font names to .afm file names (potentially,
       this  file  could remap the provided .afm file names to acceptable



      _________________________________________________________________
       TclVSrpt v1.0                Page 6                    User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



       DOS  file  names).   "fontmap" provides five pieces of information
       for   each  Postscript  font  supported:  a  minimal  pattern  for
       TclVSrpt  to  match to find a particular font name, four .afm file
       names  for the font (standard, bolded, italic, bolded and italic).
       If  you  preload  a  Postscript  font, you will need to supply the
       corresponding   .afm  files  and  entries  into  "fontmap"  before
       TclVSrpt  will  recognize the font. You can create .afm files from
       a  Postscript  font file though the "printafm.ps" utility provided
       with   Ghostscript,   a  quasi-free  postscript  interpreter  (use
       "archie" to locate nearest Internet source).                    

       The  previous  Tcl-centric  mechanism  for  determining  character
       widths  for  a  font employed by TclVSrpt prior to release 1.1 has
       been discontinued.                                              


       Postscript Encoding Schemes                                     
       __________ ________ _______                                     

       A  Postscript  encoding  scheme is how Postscript maps a character
       value  to  a  visual  representation  of that character.  Prior to
       version  1.1  of  TclVSrpt,  only the Standard Postscript encoding
       scheme  was  supported.   This caused a certain amount of hardship
       for  European  users  of  TclVSrpt.  With release 1.1 of TclVSrpt,
       two   additional   encoding   schemes   are   supported  natively:
       ISOLatin1  and  Diacritic.   ISOLatin1  contains a large number of
       characters  found in European languages.  Diacritic is an encoding
       scheme  that  blends  the best of the Standard encoding scheme and
       ISOLatin1  (particularly,  it  supports bullet characters).  Three
       files  (Standard.ps,  ISOLatin1.ps, and Diacritic.ps) are supplied
       with  TclVSrpt  to  show  how octal Tcl character constants map to
       printed characters using these different encoding schemes.      

       By  default,  TclVSrpt  will  still  use  the  "Standard" encoding
       scheme.  However,  a  new  option  to  "rptInitialize", "-encoding
       <scheme-name>"  may be used to select a different encoding scheme.
       For instance:                                                   

           rptInitialize -type Postscript -encoding ISOLatin1          

       You may add your own encoding scheme by placing an encoding scheme
       file,  "<scheme-name>.enc" in "$env(TCL_LIBRARY)/TclVS/afm".  This
       file  is  simply  a  list  of 256 postscript character image names
       given  in mapping order.  Examine one of the provided ".enc" files
       to use as a template prior to attempting this.                  







      _________________________________________________________________
       TclVSrpt v1.0                Page 7                    User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



       Including files and Inserting Text into Documents               
       _________ _____ ___ _________ ____ ____ _________               

       Two  new  commands  are  introducted  with  TclVSrpt  version 1.1:
       "rptInclude" and "rptInsert".                                   

       The  "rptInsert"  command will insert a string without any attempt
       at   formatting   it   into   the  document.   The  option  "-when
       [Postscript  |  ASCII]"  will perform this operation only when the
       document  type matches the type given in the "-when" clause.  This
       command  might  be  used  for  issuing  Postscript drawing command
       within  a  document.   The real intent for this command is with an
       eye  to  the  future for inserting Hypertext links into a document
       (proposing an HTML output type for TclVSrpt).                   

       "rptInclude"  will  copy  the  contents of the given file into the
       output  document without any attempt to format the contents of the
       file.   The  option "-when [Postscript | ASCII]" will perform this
       operation  only  when  the document type matches the type given in
       the  "-when"  clause. This command might be used for loading a set
       of  Postscript procedures to support graphics or image operations.
       A  special  case  of  this command is given in the next section on
       including EPS files into a document.                            


       Including EPS (Encapsulated Postscript) Files                   
       _________ ___ _____________ ___________ _____                   

       A  set  of  additional  options  are available to the "rptInclude"
       command  to support the inclusion of EPS (Encapsulated Postscript)
       files.   Such  an  activity is desirable for bringing in images or
       Postscript   graphics   created  outside  of  TclVSrpt  into  your
       document.   If  you  have  graphics images in another format (e.g.
       GIF,  TIFF,  JPEG,  etc.),  there  exist a number of public domain
       image   converters,  such  as  "convert"  from  ImageMagick,  that
       support  translation  to an EPS format.  An example of an EPS file
       included into a document follows:                               
                     figure 1 -- EPS Image File inclusion              

       Several  options  are  provided  to  assist  in  preparing the EPS
       display:                                                        

            -eps (included file is EPS)                                
            -epsscale (scale factor to apply to EPS image)             
            -epsalign [L|C|R] (align EPS image to left, center, or right)

       TclVSrpt will automatically issue a "rptNewLine 0" prior to an EPS
       file  inclusion.  If there is not room on the current page for the
       EPS  image,  TclVSrpt  will  automatically  issue  a "rptNewPage".
       TclVSrpt  will  advance  its internal page positioning to one line



      _________________________________________________________________
       TclVSrpt v1.0                Page 8                    User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



       beyond  the  included  EPS  image  after  the  inclusion has taken
       place.                                                          

       Tabs                                                            
       ____                                                            

       Tab  settings  may be independently defined for each style defined
       by  "rptDefStyle".  This allows for the definition of tabs to meet
       differing document component structural needs.                  

       The  tabs  for  a style may select whether tabs are resolved to an
       absolute  or nearest tab setting.  With absolute tab settings, the
       third  tab  in  a  line  will always resolve to the third tab stop
       defined.  With nearest tab settings, the third tab will resolve to
       the  next  tab  stop  to  the right of the current print position.
       Each approach has its advantages and disadvantages.             

       There are no limits to the number of tab stop settings that can be
       defined  for  a  style.   By  default,  left-aligned tab stops are
       defined  every  1/2  inch.   If you wish to define a style with no
       tabs, you must issue an empty "-tabs" option to "rptDefStyle".  

       Tab  stops  are  sorted  from  left  to right automatically within
       TclVSrpt.  You cannot define a tab stop that will move to the left
       of the previous tab stop.                                       

       Tab  stops  may be defined in any of the recognized TclVSrpt units
       of  measure  by applying a conversion suffix to the tab stop value
       (p=points,  c=centimeters,  i=inches).  If no conversion suffix is
       supplied,  the  units  of  a  tab  stop value are assumed to be in
       points (1/72 inch).                                             

       Tab  stops  may  be  left,  centered,  or  right  aligned.   If  a
       left-aligned  tab  is defined, then subsequent text starts writing
       from  that  tab  stop  location  and  procedes to the right.  If a
       center-aligned  tab  is  defined, then subsequent text is centered
       about  that  tab  stop  location.  If a tab stop is right-aligned,
       then  subsequent  text is placed such that it ends exactly at that
       tab  stop  location.  Setting the alignment type for a tab stop is
       achieved  by  placing  a  "L",  "C",  or "R" suffix after any unit
       conversion  suffix  for  the  tab stop value.  If no tab alignment
       type  suffix  is  supplied for a tab stop value, then the tab stop
       is  assumed to be left-aligned.  The following are examples of tab
       stop settings:                                                  








      _________________________________________________________________
       TclVSrpt v1.0                Page 9                    User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



            -tabs .5iL 3.5iC 6.5iR                                     

       Line Wrapping                                                   
       ____ ________                                                   

       All  styles  have line wrapping enabled by default.  However, this
       can   be   inhibited   by   setting   the   "-nowrap"   option  in
       "rptDefStyle".   When  a line is wrapped, the line split occurs at
       the  closest  word break to the right margin.  Only if there is no
       word  break  on  the line will a word be broken between lines.  If
       wrapping  is  disabled,  any text added to a line beyond the right
       margin  is  discarded.   When a line wrap occurs, the current line
       is  processed for concurrent left-right justification (if enabled)
       and  is  flushed  to the page and a new line started.  If the wrap
       character  option  ("-wrapcharacter")  has  been  enabled  for the
       current  style,  the  wrap characters defined will be added to the
       end  of  the  wrapped  line  (this  is  useful  for  printing code
       listings).   New  lines  created  by  line  wrapping will have the
       optional  wrap indentation applied to the front of the line.  With
       wrapping  enabled,  the  concept of "line" as used by "rptAddLine"
       and  "rptAddText" becomes more like that of a paragraph.  You will
       need  to  explicitly  issue  either a "rptNewLine" or "rptAddLine"
       command to flush the last line of the current paragraph.        

       Caution  should  be exercised when setting non-wrapped styles, and
       then  calling  "rptAddText"  to  incrementally add text to a line.
       Once  the right margin has been exceeded, all subsequent text will
       be  discarded,  and  the  current  line  will only be flushed by a
       "rptNewLine" or a "rptAddLine" command.                         

       Adding Lines, Adding Text, and Flushing                         
       ______ ______ ______ _____ ___ ________                         

       TclVSrpt  employs  a  "current" line buffer concept.  "rptAddText"
       simply  adds  text  to  the  end  of  that buffer (flushed only if
       wrapping  is enabled and the right margin exceeded).  "rptAddLine"
       will  flush  the  current buffer only if it has earlier text still
       in  it,  and  then  add  its text to the start of the current line
       buffer.   Neither  of  these  commands will flush the current line
       buffer  when  done.   Flushing  takes place when (1) line wrapping
       occurs;  (2)  rptNewLine  command  is  given; and most importantly
       when (3) rptNewLine command is given.                           

       "rptNewLine"  always flushes the current line buffer (if it is not
       empty)  and  adds the specified number of empty lines (defaults to
       1).   However,   giving  "rptNewLine"  an  argument  of  "0"  does
       something  very  interesting;  the  current  line  buffer  will be
       flushed  and a new line started only if the current line buffer is
       not  empty.   If  the current line buffer is empty, an "rptNewLine
       0" simply returns.                                              



      _________________________________________________________________
       TclVSrpt v1.0                Page 10                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================




       Think of "rptNewLine 0" a the "flush" command.                  

       Styles  with  text  alignments of "center" or "right" will perform
       predictably  with  an  empty  current line buffer.   However, if a
       style  change  takes  place  when  the  current line buffer is not
       empty,  and  the  text  alignment  styles  are  either "center" or
       "right",  the  results  may  not  be desirable as these alignments
       take  place  relative  to the current printing position within the
       buffer.                                                         

       Automatic, Unconditional, and Conditional Page Ejection         
       __________ ______________ ___ ___________ ____ ________         

       Page  ejection  occurs  automatically  when  adding  a line to the
       current  page  would  either  extend  into  the  page footer or be
       placed  below  the  bottom  margin  of  the  page.   A page may be
       unconditionally  ejected  and  a  new  page  started  through  the
       "rptNewPage"  command  with  no arguments.  Yet there are times in
       which  if  there  is  enough room on the current page, we want our
       text  to  go  there, and if there isn't enough room on the current
       page,  eject  and  start  the text on the next page.  "rptNewPage"
       has  two  options to support this situation. "-guardlines <count>"
       will  eject  to  a  new page if there are not <count> lines at the
       current  font  size  and  line  gapping  available  on  the  page,
       otherwise  it  will  simply  return.   "-guarddist  <length>" will
       eject  to  a  new page if there is not <length> distance available
       on  the current page before encountering the page footer or bottom
       margin;  otherwise  it  will  simply  return.  "rptNewPage" is the
       only  TclVSrpt  procedure to return a value.  It will return a "1"
       if  a  page ejection took place and a "0" if no page ejection took
       place.                                                          

       Page Headers, Page Footers, and Page Numbering                  
       ____ ________ ____ ________ ___ ____ _________                  

       The  "rptDefPage" command provides numerous options for describing
       page decorations.  By default, no page decoration is defined for a
       document.                                                       

       "rptDefPage"  may  be  called  more  than  once  per document. The
       changes  provided  in  a "rptDefPage" call will not go into effect
       until  the  next  page ejection.  With a second or subsequent call
       to  "rptDefPage",  only  those options which are to change need be
       defined as the previous settings will carry forward.            








      _________________________________________________________________
       TclVSrpt v1.0                Page 11                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



       Page  headers  may  consist  of  zero,  one,  or two lines of text
       followed  by an optional horizontal line.  The first optional page
       header  text  line  is  referred  to  as  the  title  line, and is
       centered.   It  has  its  own  font,  font  size, bolding, italic,
       underline,  and  line  gapping  options.  The second optional page
       header  line  is  referred  to  as the subtitle line and is placed
       below  the  title line.  It may have zero, one, two, or three text
       components  placed  at  the  left  margin,  page center, and right
       margin.   The  subtitle line has its own font, font size, bolding,
       italic,  underline,  and  line gapping options.  The optional page
       header  horizontal  line (title bar) is placed below the subtitle,
       and  has  options for its thickness, indentation from the left and
       right  margins, and a gap to the first line of text in the body of
       the page.                                                       

       Page  footers  may  consist  of  zero or one line of text below an
       optional  horizontal  line.  The optional line of page footer text
       may  have  zero, one, two, or three text compoenents placed at the
       left  margin,  page center, and right margin.  The page footer has
       its  own font, font size, bolding, italic, underline, and line gap
       options.   The line gap option for the page footer pertains to the
       distance  above  to  page  footer  text.  The optional page footer
       horizontal  line  (footer  bar)  is  placed  above the page footer
       text,  and  has  options  for its thickness, indentation from left
       and  right  page  margins, and gap to the last line of text in the
       body of the page.                                               

       Although  page  header title, subtitle and page footers have style
       definition  entries, the preferred way to set their font and other
       options is through the "rptDefPage" command.                    

       Page  numbers  are  not  automatically  provided,  but will become
       activated  if  any  of  the  page numbering options are set in the
       "rptDefPage" command.                                           

       Page  numbers  may  be placed in one of six locations on the page:
       the  three  text  areas of the subtitle or the three text areas of
       the  page  footer.   The values of the page number location may be
       any  number  of,  and any ordering of the following option values:
       "top",  "bottom", "left", "center", "right", and "alternate".  The
       default  page  number  location  is  "bottom"  and  "center".  The
       "alternate"  option  will  cause  a  "left" or "right" page number
       location  to switch sizes on every other page.  When a page number
       alternates  between  sides,  the  text  on  the opposite side will
       alternate  sides  as  well.  An alternating page number will start
       on either the "left" or "right", which must be specified as well. 





      _________________________________________________________________
       TclVSrpt v1.0                Page 12                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



       Page  numbers  may  have an optional prefix string and an optional
       suffix  string  assigned.   An  example  of  a  prefix  string is:
       "Page".   An  example  of a suffix string is: " of 23".  (There is
       no  programatic  means  within  TclVSrpt  to  know how may pages a
       document will consume, so this last example is a bit of a fudge). 

       Page  numbers  may be given a starting value.  By default, this is
       "1".                                                            

       Page   numbers   may  be  presented  in  three  different  styles:
       "numeric"    (default),    roman    (lower-case),   and   caproman
       (upper-case).                                                   

       Error Processing                                                
       _____ __________                                                

       Error  reporting  in  TclVSrpt  is  minimalized.  When an error is
       encountered,  such as in an invalid command option name or invalid
       font  name,  a  runtime  message  may  be  issued to stderr, but a
       reasonable  default  value  will  be  provided and processing will
       continue.   The  upside  to  this  approach  is  always  getting a
       document  out  of TclVSrpt. The downside is that this document may
       not look the way you expect it to.                              

       Performance                                                     
       ___________                                                     

       TclVSrpt  has,  simply  stated, lousy performance compared to what
       one  might  find  from  a  compiled  document  preparation system.
       There  are  probably  several  things  that could be done to boost
       performance  within TclVSrpt - specifically reducing the number of
       times  iteration  occurs  over each character.  However, even such
       improvements  will  not  compete  well  with  a  compiled program.
       TclVSrpt  may  be  converted to C when I have a few hours under my
       belt  with  the  new  dynamic  library  feature  of  Tcl 7.5.  The
       overriding  design  goal  of TclVSrpt, even above performance, was
       to  create  a  portable  facility that was easy to install and use
       with  any  Tcl  application  without  having to play the "link yet
       another extension into Tcl" game.                               

       I  have  observed  that a couple of small improvements to the core
       Tcl  language  that would benefit TclVSrpt greatly, and would most
       probably benefit other Tcl applications:                        

       *  In-place list and string indexed and ranged element
          modification                                                 
       *  In-place list and string appending                           






      _________________________________________________________________
       TclVSrpt v1.0                Page 13                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



       Support and Feedback                                            
       _______ ___ ________                                            

       TclVSrpt is distributed with the same licensing spirit as Tcl/Tk. 
       This  copyright must remain in the TclVSrpt source code and files,
       and  acknowledged  if  TclVSrpt or its derivative is redistributed
       (See  file  "licenseing.terms").   No  express or implied warranty
       that  this  software is suitable for any purpose is given by me or
       other parties that might have interest in TclVSrpt.             

       However,  I  am  interested in any feedback that you might provide
       on  TclVSrpt and will attempt to respond to any problems you might
       encounter with it.  Send all bug reports and correspondence to: 

            steven@cirque.com                                          





































      _________________________________________________________________
       TclVSrpt v1.0                Page 14                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================





       rptAddLine                                                      
       __________                                                      

       Adds  the text arguments to the page as a single line of text.  If
       the  current  line  buffer  is  not  empty,  an  "rptNewLine 0" is
       automatically  issued  to  flush  the  prior  accumulation  before
       adding  the  text  arguments.  "rptAddLine" does not force a flush
       after  adding  its  text  to  the  current  line  buffer.   Only a
       subsequent  "rptAddLine" or "rptNewLine" will flush the buffer and
       add  the  line  to  the  page.  Prior to adding the provided text,
       "rptAddLine"  will  process  the  "-lineindent"  option  value and
       "-lineprefix"  option of the current style in effect. Embedded tab
       characters  are  supported  by  rptAddLine,  but  embedded newline
       characters  are  not  (they  will be discarded).  The line of text
       supplied  to  "rptAddLine"  may either be a list of separate words
       or  a  quoted  string.   The  quoted string form of adding text to
       "rptAddLine"  is preferred as it will preserve white space between
       words.                                                          
                                                                       
       Prerequisites:                                                  
            rptDefPage                                                 
                                                                       
       Usage:                                                          
            rptAddLine [[ <text> ]...] | " <text string> "             
                                                                       
       Examples:                                                       
            rptAddLine XYZ Corporation                                 
            rptAddLine "\t123 Main Street"                             
            rptAddLine "\tAnytown, CO  01234"                          
                                                                       
                                                                       


       rptAddText                                                      
       __________                                                      

       Add  the text arguments to the current line buffer starting at the
       next  available  print  position.   "rptAddText"  can  be  used to
       incrementally  add  text  to a line (with perhaps different styles
       in  effect), or to add a number of lines of text to a page through
       one  command  (lines  are delimited by embedded newline characters
       in  the  argument  list).  "rptAddText" will correctly process tab
       characaters  in  context  of  the current line buffer.  Passing an
       empty  string  argument  to  "rptAddText"  will issue an automatic
       "rptNewLine  1", flushing out the current line buffer and adding a
       empty line to the page.                                         





      _________________________________________________________________
       TclVSrpt v1.0                Page 15                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



                                                                       
       Prerequisites:                                                  
            rptDefPage                                                 
                                                                       
       Usage:                                                          
            rptAddText [[ <text> ]...]                                 
                                                                       
       Examples:                                                       
            rptAddText The IRS places the burden of proof of compliance o
            rptAddText "applicable tax regulations on the individual taxp
                (text may be a list or separate arguments)             
                                                                       
            rptAddText "\\t\\tXYZ Corporation\\n\\t\\t\\t123 Main Street"
                (multi-line with embedded tabs)                        





































      _________________________________________________________________
       TclVSrpt v1.0                Page 16                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================





       rptDefPage                                                      
       __________                                                      

       This  procedure  defines  the page decorations for the page.  This
       procedure  should  be  called  prior  to  adding  any  text to the
       document.  Once  this  procedure  has  been invoked, it may not be
       invoked  again  for  the document.  Most options to this procedure
       are  clearly  named.  Invoking "rptDefPage" with no arguments will
       define a page with no page decorations.                         
                                                                       
       Prerequisites:                                                  
            rptDefPaper                                                
                                                                       
       Usage:                                                          
            rptDefPage [[ <-option> [ <value> ...]] ...]               
                                                                       
       Options:                                                        
            -title <centered title text>                               
            -titlefont <font name for title text>                      
            -titlesize <title text font size>                          
            -titlebold     (set title text font to bold)               
            -titleitalic   (set title text font to italic)             
            -titleunderline (underline the title text)                 
            -titlegap <spacing below title>                            
            -subtitle <centered subtitle text>                         
            -subtitleleft <left-aligned subtitle text>                 
            -subtitlecenter <centered subtitle text>                   
            -subtitleright <right-aligned subtitle text>               
            -subtitlefont <font name for subtitle text (s) >           
            -subtitlesize <subtitle text font size>                    
            -subtitlebold  (set subtitle text font to bold)            
            -subtitleitalic (set subtitle text font to italic)         
            -subtitleunderline (underline the subtitle text)           
            -subtitlegap <spacing below subtitle>                      
            -titlebar      (show horizontal line below title/subtitle) 
            -titlebarindent <inset from left and right margins>        
            -titlebarthick <thickness of line>                         
            -titlebargap <spacing below titlebar>                      
            -footer <centered footer text>                             
            -footerleft <left-aligned footer text>                     
            -footercenter <centered footer text>                       
            -footerright <right-aligned footer text>                   
            -footerfont <font name for footer text>                    
            -footersize <footer text font size>                        
            -footerbold    (set footer text font to bold)              
            -footeritalic  (set footer text font to italic)            
            -footerunderline (underline the footer text)               



      _________________________________________________________________
       TclVSrpt v1.0                Page 17                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



            -footergap <spacing above footer text>                     
            -footerbar     (show horizontal line above footer)         
            -footerbarindent <inset from left / right margins>         
            -footerbarthick <thickness of line>                        
            -footerbargap <spacing above footerbar>                    
            -pagenocallback <Tcl procedure name to call with page number 
            -pagenoprefix <page number prefix string>                  
            -pagenosuffix <page number suffix>                         
            -pagenostart <starting page number>                        
            -pagenostyle numeric | roman | caproman                    
            -pagenolocation top | bottom | left | center |             
                right | alternate [ <location option> ]...             
                                                                       
       Defaults:                                                       
            -title ""                                                  
            -titlefont Courier                                         
            -titlesize 18p                                             
            -titlegap 2p                                               
            -subtitleleft ""                                           
            -subtitlecenter ""                                         
            -subtitleright ""                                          
            -subtitlefont Courier                                      
            -subtitlesize 12p                                          
            -subtitlegap 2p                                            
            -titlebarindent 0                                          
            -titlebarthick .1p                                         
            -titlebargap 2p                                            
            -footerleft ""                                             
            -footercenter ""                                           
            -footerright ""                                            
            -footerfont Courier                                        
            -footersize 12p                                            
            -footergap 2p                                              
            -footerbarindent 0                                         
            -footerbarthick .1p                                        
            -footerbargap 2p                                           
            -pagenoprefix ""                                           
            -pagenosuffix ""                                           
            -pagenostart 1                                             
            -pagenostyle numeric                                       
            -pagenolocation bottom center                              
                                                                       
       Example:                                                        
            rptDefPage \                                               
                -title "Sales Revenue" -titlefont Helvetica \          
                -titlesize 18 -titlebold -titlegap 2 \                 
                -subtitle "January 1994" -subtitlefont Helvetica \     
                -subtitlesize 14 -subtitlebold -subtitlegap 2 \        



      _________________________________________________________________
       TclVSrpt v1.0                Page 18                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



                -titlebar -titlebarindent 0 -titlebarthick .125i \     
                -titlebargap .5i \                                     
                -footerleft "XYZ Corporation" \                        
                -footerright "Company Confidential" \                  
                -footerfont Times -footersize 8 -footeritalic \        
                -footergap 4 \                                         
                -footerbar -footerbarindent 3i -footerbarthick .1p \   
                -footerbargap .5i \                                    
                -pagenoprefix "Page " -pagenoloc bottom center         










































      _________________________________________________________________
       TclVSrpt v1.0                Page 19                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================





       rptDefPaper                                                     
       ___________                                                     

       Defines  and  sets  the paper size, paper orientation, and margins
       for   the  document.   Once  rptNewPage  has  been  called  for  a
       document, it may not be called again.                           
                                                                       
       Prerequisites:                                                  
            rptInitialize                                              
                                                                       
       Usage:                                                          
            rptDefPaper [ <-option> <value> ] ...                      
                                                                       
       Options:                                                        
            -pagesize                                                  
                letter     (8.5"x11"; 21.59x27.94 cm; 612x792 pts)     
                legal      (8.5"x14"; 21.59x35.56 cm; 612x1008 pts)    
                tabloid    (11"x17"; 27.94x43.18 cm; 792x1224 pts)     
                ledger     (17"x11"; 43.18x27.94 cm; 1224x792 pts)     
                statement  (5.5"x8.5"; 13.97x21.59 cm; 396x612 pts)    
                executive  (7.5"x10"; 19.05x25.5 cm; 540x720 pts)      
                a3         (11.69"x16.53", 29.7x42 cm;842x1190 pts)    
                a4         (8.26"x11.69"; 21x29.7 cm; 595x842 pts)     
                a5         (5.83"x8.26";14.82x21 cm; 420x595 pts)      
                b4         (11"x14.33"; 25.72x36.41 cm; 729x1032 pts)  
                b5         (7.17"x10.13"; 18.20x25.72 cm; 516x729 pts) 
                folio      (8.5"x13"; 21.59x33.02 cm; 612x936 pts)     
                quarto     (8.47"x10.83"; 21.52x27.52 cm; 610x780 pts) 
                10x14      (10"x14"; 25.4x35.56 cm; 720x1008 pts)      
            -customwidth <pagewidth size>                              
            -customheight <pageheight size>                            
            -orientation portrait | landscape                          
            -margins <distance from all outside edges of paper>        
            -leftmargin <distance from left edge of paper>             
            -rightmargin <distance from right edge of paper>           
            -topmargin <distance from top edge of paper>               
            -bottommargin <distance from edge of paper>                
            -leftdead <non-printable zone width on left edge of paper> 
            -rightdead <non-printable zone width on right edge of paper>
            -topdead <non-printable zone width on top edge of paper>   
            -botdead <non-printable zone width on bottom edge of paper>
            -pointspercharacter <width of ASCII character in points>   
            -pointsperline <height of ASCII line line points>          
                                                                       
       Defaults:                                                       
            -pagesize letter                                           
            -orientation portrait                                      



      _________________________________________________________________
       TclVSrpt v1.0                Page 20                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



            -margins 0                                                 
            -leftdead                     (0i Postscript, .25i ASCII)  
            -rightdead 0                  (0i Postscript, .25i ASCII)  
            -topdead 0                    (0i Postscript, .5i ASCII)   
            -botdead 0                    (0i Postscript, .5i ASCII)   
            -pointspercharacter 7.2p      (10 characters per inch)     
            -pointsperline 12p            (6 lines per inch)           
                                                                       
       Examples:                                                       
            rptDefPaper -pagesize legal   (set paper to legal size)    
                                                                       
            rptDefPaper -orientation landscape -pagesize letter        
                (rotated letter-sized page)                            
                                                                       
            rptDefPaper                                                
                (accept all defaults)                                  
                                                                       
            rptDefPaper \                                              
                -pagesize a4 \                                         
                -orientation portrait \                                
                -leftmargin 4c \                                       
                -topmargin 4c \                                        
                -rightmargin 1.5c \                                    
                -bottommargin 1.5c \                                   
                (explicitly describe page layout)                      


























      _________________________________________________________________
       TclVSrpt v1.0                Page 21                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================





       rptDefStyle                                                     
       ___________                                                     

       Define  a  mnemonic  name  that  contains  the  definition  of the
       appearance  and  properties  of  printed  text.  Once the mnemonic
       name  has  been  defined,  it  can  be  put  into  effect  for any
       subsequent  text through the "rptSetStyle" command.  "rptDefStyle"
       itself  causes  no  change in the appearance of text.  Through the
       rptDefStyle  command,  a  number  of  text appearance and property
       options   may   be  defined  including  the  font  type,  bolding,
       italicizing,  font  size,  and  underlining  of all text until the
       next  "rptSetStyle"  command  is  encountered.   This procedure is
       also  use  for  defining  a style that sets the text alignment and
       wrapping  characteristics  of  subsequent  text  (from the current
       location  on  page).   All settings desired must be defined by the
       "rptDefStyle"  command  as their is no defaulting or carry-forward
       of style settings between occurances of "rptSetStyle".          
                                                                       
       Prerequisites:                                                  
            rptInitialize                                              
       Usage:                                                          
            rptDefStyle [ <-option> [ <value> ]] ...                   
       Options:                                                        
            -name <unique style name>                                  
            -font          (minimum specification shown to right)      
                AvantGarde                (avant)                      
                Bookman                   (book)                       
                Courier                   (cour)                       
                Helvetica                 (helvetica)                  
                Helvetica-Narrow          (helvetica-n)                
                NewCenturySchlbk          (newc)                       
                Palatino                  (pala)                       
                Symbol                    (symb)                       
                Times                     (time)                       
                ZapfChancery-MediumItalic (zapfc)                      
                ZapfDingbats              (zapfd)                      
            -bold          (turn on font bolding)                      
            -italic        (turn on font italicizing)                  
            -size <font size>                                          
            -gap <gap between lines>                                   
            -underline     (turn on underlining)                       
            -align                                                     
                left       (left justify)                              
                right      (right justify)                             
                center     (center justify)                            
                justify    (concurrent left-right justify)             
            -tabs [[ <tab settings> ] ...]                             



      _________________________________________________________________
       TclVSrpt v1.0                Page 22                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



            -tabstyle absolute | nearest                               
            -leftindent <left margin indentation offset for this style>
            -rightindent <right margin indentation offset for this style>
            -firstindent <additional left indentation for first line>  
            -lineprefix <string to prefix each line of this style with>
            -wrap          ([default] turn on line wrapping)           
            -nowrap        (turn off line wrapping)                    
            -wrapindent <left margin indentation offset for wrapped lines
            -wrapcharacters <string to terminate a line with to show wrap
       Defaults:                                                       
            -font Courier                                              
            -size 10                                                   
            -gap 2p                                                    
            -align left                                                
            -wrap                                                      
            -tabs .5iL 1iL 1.5iL 2iL 2.5iL 3iL 3.5iL 4iL 4.5iL 5iL 5.5iL 
            -leftindent 0                                              
            -rightinent 0                                              
            -firstindent 0                                             
            -lineprefix ""                                             
            -wrapindent 0                                              
            -wrapcharacter ""                                          
       Examples:                                                       
            rptDefStyle -name stdbody -font Times -italic -size 10 \   
                -align justify -wrap                                   
                ( ... add lines of text to report ... )                
            rptSetStyle stdbody                                        
                (all following text will have properties of "stdbody") 























      _________________________________________________________________
       TclVSrpt v1.0                Page 23                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================





       rptDone                                                         
       _______                                                         

       Signals  the  completion  of  the  document generation and handles
       disposition  of  the  document.   If neither a printer option or a
       file name option are specified, the report is discarded.        
                                                                       
       Prerequisites:                                                  
            rptDefPage                                                 
                                                                       
       Usage:                                                          
            rptDone [ <-option> [ <value> ]] ...                       
                                                                       
       Options:                                                        
            -P <printer>   (send report to the named printer)          
            -f <file name> (save the report to the named file)         
            -copies <count> (generate <count> copies of report)        
                                                                       
       Defaults:                                                       
            -copies 1                                                  
                                                                       
       Examples:                                                       
            rptInitialize -type text                                   
            rptDefPaper -pagesize letter -margins 1i                   
            rptDefPage -title /etc/passwd                              
            rptDefStyle -name text -font Courier -size 10 -wrapchar " \"
            rptAddText [exec cat /etc/passwd]                          
            rptDone -Pps -f ~/myetcpasswd -copies 2                    






















      _________________________________________________________________
       TclVSrpt v1.0                Page 24                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================





       rptInclude                                                      
       __________                                                      

       Include  an  external  file  into  the document without processing
       based   on  document  output  type.   Additionally,  this  command
       supports the inclusion of EPS (Encapsulated Postscript) files.  
                                                                       
       Prerequisites:                                                  
             rptDefPage                                                
                                                                       
       Usage:                                                          
            rptInclude [ <-option> <value> ]                           
                                                                       
       Options:                                                        
            -when Postscript | ASCII                                   
            -file <filename>                                           
            -eps                                                       
            -epsscale <scalefactor>                                    
            -epsalign L | C | R                                        
                                                                       
       Defaults:                                                       
            -when ASCII                                                
            -epsscale 1.0                                              
            -epsalign L                                                
            -file ""                                                   
                                                                       
       Examples:                                                       
            rptInclude -when Postscript -eps -epsscale .5 -epsalign L -fi
                (include a logo image at left margin, scale to 1/2 origin
                                                                       


       rptInitialize                                                   
       _____________                                                   

       Initialize   or   Re-initialize  (discarding  previous  work)  the
       TclVSrpt  package for the creation of a new document.  Returns the
       current TclVSrpt version number.                                
                                                                       
       Prerequisites:                                                  
            (none)                                                     
                                                                       
       Usage:                                                          
            rptInitialize [ <-option> <value> ]                        
                                                                       
       Options:                                                        
            -type Postscript | ASCII                                   
            -encoding <Postscript Encoding Scheme>                     



      _________________________________________________________________
       TclVSrpt v1.0                Page 25                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



                                                                       
       Defaults:                                                       
            -type ASCII                                                
                                                                       
       Examples:                                                       
            rptInitialize -type Postscript -encoding ISOLatin1         
                (set report type to postscript with ISOLatin1 encoding)
            rptInitialize -type ASCII                                  
                (set report type to text)                              










































      _________________________________________________________________
       TclVSrpt v1.0                Page 26                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================





       rptInsert                                                       
       _________                                                       

       Based  upon  a  document's type, insert a string into the document
       without formatting or inserting newlines.                       
       Prerequisites:                                                  
             rptDefPage                                                
                                                                       
       Usage:                                                          
            rptInsert [ <-option> <value> ]                            
                                                                       
       Options:                                                        
            -when Postscript | ASCII                                   
            -string <filename>                                         
                                                                       
       Defaults:                                                       
            -when ASCII                                                
            -string ""                                                 
                                                                       
       Examples:                                                       
            rptInsert -when ASCII -string " <HREF=\"http://www.cirque.com
                (insert an html link into document)                    
                                                                       


       rptNewLine                                                      
       __________                                                      

       If  any  text is present in the current line buffer, it is flushed
       to  the  page,  then the number of blank lines specified are added
       to  the  page.  Issuing "rptNewLine 0" will flush the current line
       if   it  is  not  empty,  otherwise  it  will  do  nothing.   This
       "-distance"  option  will  create  the  specified  amount of empty
       space on the page.                                              
                                                                       
       Prerequisites:                                                  
            rptDefPage                                                 
                                                                       
       Usage:                                                          
            rptNewLine [ <count> ]                                     
            rptNewLine -distance <size of open vertical space>         
       Options:                                                        
             <count> (number of empty lines to print)                  
                                                                       
       Defaults:                                                       
            1                                                          
                                                                       
       Examples:                                                       



      _________________________________________________________________
       TclVSrpt v1.0                Page 27                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



            rptAddText "XYZ Corporation"                               
            rptNewLine 0                                               
                ( ... )                                                
            rptNewLine 5   (add 5 blank lines to page)                 
                                                                       


       rptNewPage                                                      
       __________                                                      

       Conditionally  or unconditionally eject the current page and start
       subsequent  print  at the top of a new page.  This command returns
       a "1" if a page ejection occurred or a "0" if it did not.       
                                                                       
       Prerequisites:                                                  
            rptDefPage                                                 
                                                                       
       Usage:                                                          
            rptNewPage [ <-option> <value> ]                           
                                                                       
       Options:                                                        
            -guardline     <number of lines>                           
                (eject page if fewer than these lines left on page)    
                                                                       
            -guarddist     <distance>                                  
                (eject page if bottom of page is less than this distance)
                                                                       
       Examples:                                                       
            rptAddLine "The following are new account contacts:"       
            rptNewLine 0                                               
            rptSetStyle companylist                                    
            rptNewPage -guardline 3                                    
            rptAddLine "XYZ Corporation"                               
            rptAddLine "   123 Main Street"                            
            rptAddLine "   Anytown, CO  01234"                         
                                                                       
                                                                       


       rptSetStyle                                                     
       ___________                                                     

       Put  into  effect  the settings previously registered to the style
       name  defined  by  "rptDefStyle" for all subsequent text; or until
       the   next  "rptSetStyle"  is  encountered.   If  the  style  name
       provided  is not recognized as that of a style previously defined,
       no change is made from the current style settings.              






      _________________________________________________________________
       TclVSrpt v1.0                Page 28                   User Guide
                                 TclVSrpt v1.0                         
                                 ________ ____                         
                         Tcl Very Simple Report Writer                 

       =================================================================



                                                                       
       Prerequisites:                                                  
            rptDefPage                                                 
                                                                       
       Usage:                                                          
            rptSetStyle <stylename>                                    
                                                                       
       Options:                                                        
             <stylename>                                               
                                                                       
       Examples:                                                       
            rptDefStyle -name stdbody -font time -italic -size 10 \    
                -align justify -wrap                                   
                ( ... add lines of text to report ... )                
            rptSetStyle stdbody                                        
                (all following text will have the properties of "stdbody"



































      _________________________________________________________________
       TclVSrpt v1.0                Page 29                   User Guide
