CONCEPTS, PRIMER, AND TIPS

UnForm is a very powerful tool, with dozens of commands and features.  It can be difficult to grasp the basics from such a large toolset, but the basics are really very simple.  Once UnForm is installed by an administrator, the only skills required to develop typical business forms are an ability to edit text files on your system, and an ability to execute UnForm as needed to test your changes.  The Windows-based UnForm Design Tool can provide an efficient environment for rule file development, if desired.

Here are some basic concepts that you should understand before proceeding:

•UnForm processes text input and produces formatted output.  The input can come from a file or, on UNIX, can come from UnForm's standard input.  The output can go to a file or a device on either the server or the client, or on UNIX can go to the client's standard output.
 

•UnForm can also process pre-formatted application output, if that output comes to UnForm as PostScript.  See the UnForm AFO chapter for more information.
 

•UnForm uses a rule file to define all the form and print jobs it might process.  In that rule file are one or more rule sets, each of which represents one form or print job.  Rule files and the rule sets they contain are simply text files with command lines, which you can edit with any text editor.  The rule file should be stored in the UnForm directory, and specified with the "-f rulefile" command line argument.  If you don't specify the rule file on the command line, then the default rule file named at installation is used.
 

•Unless the "-r ruleset" command line option is used, UnForm reads the first page of input and compares that first page with all the detect statements found in each rule set.  These statements instruct UnForm to look for text or patterns at specified locations or lines (or anywhere on the page).  If all the detect statements for a given rule set match the contents of the first page, then UnForm selects that rule set and begins to produce output.  If a match is not found, then the next rule set is tested, and so on until all the rule sets have been tested.  If no match is found, then UnForm will pass the job through without any changes or enhancements, or in the case when a pdf or pcl driver is specified with a –p driver command line option, will produce a text job scaled to fit each page.
 

•Each job has its own geometry, that is, the basic columns and rows to which UnForm scales everything.  If you specify cols 85, then UnForm will scale each character and all the enhancement positions and sizes to 1/85th of the printed space between the margins.  In a sense, the job wraps enhancements around the text input as it is sent to the output.
 

•The commands in the rule set determine what enhancements are applied.  These can be text additions, font changes, boxes, shade regions, barcodes, images, and more.  Each change is controlled by a command line in the rule set, such as box 5.5,2,20,4.
 
Some commands don't add output, but instead modify the text input to UnForm.  The text will normally print in the Courier font, scaled to the number of columns you specify.  You can change the attributes of that text in any rectangular region with font command, or manipulate it with the move and erase commands.
 

•Some commands control the printer.  For example, the tray command can select the input tray on a laser printer, and the bin command can select an output bin.
 

•You can have UnForm generate multiple copies of each page of input.  Each copy can have unique characteristics by using if copy n blocks.  This is a simple structure that starts with a line "if copy n", where n is the copy number, followed by any number of lines of enhancement commands, followed by a line "end if".

Creating Rule Files with the UnForm Design Tool

•Obtain sample output from your application for the form you want to design.  Most applications provide the means to print to a text file.  If no other means exists, you can define a printer that prints to UnForm with a –debug command line option, in which case UnForm will leave a copy of the input stream on the server, under the UnForm directory, in temp/jobno.in.  You can find job numbers and their print times and size with the uf101c –myjobs command.
 
Store this text file in the UnForm directory on the server.
 

•Access the UnForm Design Tool from a web browser, and login.  Create a new rule file, then a new rule set, then set the sample to the file created above.  The UnForm Designer is a rule file editor with on line help, command editors, and drawing and preview capabilities.
 

Manual Rule Set Creation Steps

•Obtain sample output from your application for the form you want to design.  This output can be printed to a text file, or you can simply use two printers defined with UnForm, one with the crosshair option (-x), the other with normal output.  If you are working on a Windows system or have network access from a Windows system to the server where UnForm operates, you can use the pdf driver and an Acrobat Reader to save paper while developing the design.
 

•Print your sample through UnForm with the crosshair option turned on.  This will provide you with a grid of text positions printed by your application.  If you have a file printed by your application, the command line for a grid would look like this: uf101c –x 1-99 –i input-file –o output-device or uf101c -x 1-99 –i input-file | lp -dxxx .  If your sample does not contain form-feeds, you can add a –page n option to tell UnForm how many lines are to be read per page.
 

•Since you will be printing this sample many times, you may wish to create a script or batch file to automate the command line, which will be something like: uf101c –i input-file –f rule-file –o output-device or uf101c –i input-file –f rule-file | lp -dxxx.
 

•Looking at the text of the input file, determine what makes this job unique.  Sometimes there is a title, such as "PURCHASE ORDER", printed at a specific position.  That may be enough to determine the uniqueness of the document so just add detect column, row, "PURCHASE ORDER".  You might need to find multiple patterns by using more than one detect statement.  Patterns are specified by starting the detect string argument with a ~ character.  The balance of the string is a regular expression.  Common syntax elements for regular expressions include "." to match any character, [0-9] to match any digit, [A-Z] to match any capital letter, and * to match any number of repetitions of the prior match character.  A more complete description of regular expressions is in the Regular Expressions chapter.
 
To try out your detect statement(s), try adding just those statements plus a single text command, then print the job.  If your job prints with that text in addition to the text from your application, then your detect statements are working.  This is what the rule set will start to look like:
 
[purchase_order]
detect 40,2,"PURCHASE ORDER"
text 1,1,"Test Text"
 
Note that it is possible to execute a rule set without detect statements, by adding "-r ruleset" to the command line.
 

•The rest of the form design is simply a matter of adding commands for text, boxes, and shade regions.  It is usually best to work consistently from top to bottom, left to right in the different sections of the form.  Use comments (lines starting with #) liberally; they make the rule set easier to follow when you come back later to make a change.

A good place to see complete rule sets are the sample rule files provided with UnForm, simple.rul and advanced.rul.  These two files are thoroughly documented in Sample Rule Sets chapter.   In addition to simple form designs, the samples show techniques with complex designs, such as jobs with multiple formats of input, and jobs that have embedded programming capabilities.

Tips and Techniques

*Always start with a crosshair pattern, so the basic text provided by the application, and its exact placement, can be seen.  As the crosshair mode prints just the first page, use short versions of the reports or forms.  There are several ways to create a crosshair version of a report:
 

oPrint the report to a file, then process that file with UnForm's command line, such as uf101c -i filename -o output-device –x
 

oAdd a printer configured with the "-x" option, and print to that printer.

 
 
If your report doesn't contain form-feed characters at the end of the page, then you should print just one page worth of data, or add a –page n option to the command line.  Otherwise, UnForm will assume the page is made up of as many lines as are printed, up to 255 lines.
 

*Use detect statements to identify each form.  UnForm is designed to process all your reports and just enhance those it can identify; all others are passed through unchanged.  This is easier to set up than forcing a given printer device to be named for every form or report, as is required of most form packages.
 

*Specify the columns and rows for the form or report using the cols and rows commands.  If this isn't done, then UnForm will assume 80 columns by 66 rows.  An exception to this assumption is that if a page keyword is used, then the rows will be taken to be that value unless a rows command is also present.
 

*Remove unwanted text with the erase command, or move it with the move command.  In programming code, such as in the prepage or precopy routines, you can modify the text$[] array directly or via the set() function.
 

*Apply attributes to the text with the bold, italic, light, or underline commands.  These apply to the text generated by the application (not to text you add with the text keyword).  Or use the font command, which can apply any of these attributes as well as apply other characteristics to the application text data.
 

*Use the font command to modify the font of text from the application,  All text printed by the application will print in Courier unless changed with the font command.   When changing to a proportional font, be sure to make the changes to specific logical regions, such as a column of prices.  If you change the font for the entire page, then columns will not align properly.
 

*Add text, such as headings or messages, with the text command.  Text can be literals enclosed in quotes, named values from a substitution file if prefixed with "@", environment variables prefixed by $, or an expression enclosed in { } characters.  Text can be rendered at any size and in any font supported by the printer or device.  Remember that fixed pitch fonts, such as Courier, are sized in characters per inch, while proportional fonts are sized in points.  The larger the cpi, the smaller the font.  The larger the point size, the larger the font.
 

*Add shading and box drawing with the shade and box commands.  Reverse shading is accomplished by shading a region with 100% (black) shading, and using a font or text command to modify the text to shading of 0% gray (white).  Simply using a row or column value of 1 will draw lines.  To draw a box and shade the interior, use the shade option of the box keyword.
 

*Add logos and other images with the image command.  With this command, UnForm normally looks specifically for PCL raster images (or PDF images if the pdf driver is used) in the file.  UnForm can also be configured to use Image Magick or Image Alchemy for on-the-fly conversion of traditional image formats to native PCL, EPS, or PDF.
 

*Use the attach command to add overlays or attachments.  This command does not search only for image data.  It does, however, search for and remove initialization and form-feed codes.
 
Attachments should be treated as separate copies: use the pcopies command to allocate enough copies, then use if copy n to add the attachment, notext to suppress the application text output, and make sure other enhancements don't apply to the attachment copy.
 
To create an overlay, use the attach command, but allow the text and enhancements to also be applied on the same copy.  Attachment documents for PCL output can be created using a PCL5 printer on Windows, selecting the Print to File option or setting it up to use a FILE: port.  For PDF attachments, use Adobe Distiller, choosing PDF 1.5 or lower compatibility to avoid some features that are not compatible with UnForm's PDF parsing engine.
 

*If the application doesn't use form-feeds at the end of each page, then use the page keyword to tell UnForm how many lines are used for each page.   Many applications, especially with forms, will use just line-feeds when scrolling to the top of each form.  UnForm will need to be told where the end of a page is, in this case.
 

Use Business Basic programming as a powerful macro language.  All the data that is sent by the application to each page is available for your use.  Use this data to get fax numbers and generate faxed copies, or to print shipping labels derived from the invoice ship-to addresses while packing lists are printed, or to add additional information such as costs or comments to forms, or to print logs or send email.  See the precopy{} command reference, and the Programming Code Blocks chapter for more information.