Appendix C

Configuring Xprinter

This appendix provides detailed instructions on configuring a printer so you can print from the Xilinx application. The information in this appendix applies only to workstation applications.

You must have the following Wind/U files installed correctly to print from your application.

• PPD (PostScript Printer Description)
  
  PPD files provide Wind/U with model-specific information like paper tray configuration, supported paper sizes, available ROM fonts, and so forth.
  
  
• AFM (Adobe Font Metric) and TFM (Tagged Font Metric)
  
  AFM and TFM files provide font metric information for all fonts in PostScript and PCL5 printers, respectively.
  
  
• Other files
  
  Various other files are copied to $WUHOME/xprinter and are required by Wind/U when printing. These include xprinter.prolog (PostScript prolog), psstd.fonts and pclstd.fonts (provide PostScript/PCL5 to X Window System font name mappings), and rgb.txt.
  
  

Make a complete, as-is copy of the directory $WUHOME/xprinter and include it in the installation for your product. None of the files from this directory require modifications in most environments.

Note: All of the files in $WUHOME/xprinter are the property of Bristol Technology and are licensed to you under the terms of the Wind/U license agreement. You can freely distribute these files as long as they are bundled with your application. Consult the Wind/U license agreement for further details.

Configuring .WindU

Once you have installed the required printer configuration files on your system, you must configure the .WindU file in your home directory (or SYS$LOGIN:WINDU.INI) for printing.

You can modify the .WindU file either by using a text editor or the Xprinter Printer Setup dialog box. Using the dialog box is recommended, because it reduces the risk of error. The instructions in this appendix describe how to edit the .WindU file, and then provide step-by-step instructions for performing the same task with the Printer Setup dialog box. These instructions are provided to help you configure your printer.

Printer Information

When you configure Wind/U to print, you need to know the following information for each printer you want to access.

• Name of the printer description (PPD) file
  
  
• The command used to send output to a printer
  
  

PPD Files

The Wind/U installation media includes the PPD files for most commonly used printers. To verify that the PPD file associated with your printer is included, look at the Printer Devices dialog (from the Printer Setup dialog, click Install and Add Printer). If your printer model is listed, Wind/U has a PPD file for your printer. If your printer model is not listed, contact your printer vendor to obtain the PPD file for your printer.

Unix Print Command

The command used to send output to a specific printer depends on the platform, the printer, and how the printer is connected to your system. For example, if a printer is connected directly to your system, the following might be valid print commands.

If your printer is connected to a different system on your network, your printer command will specify how to connect to that system. For example, if a printer is connected to the system bandit on your network, any of the following might be valid print commands

rsh bandit lp -d ps -t$XPDOCNAME

Note: In these examples, $XPDOCNAME represents the name of the output file sent to the printer with the specified command. If you use a multi-word file name, such as a print file, you must enclose the $XPDOCNAME in quotation marks as follows. You must escape the quotation marks in the remote command, because rsh strips them out if you do not.

Configuring Wind/U for Printing

Once you know the name of the PPD file and the print command for each printer you want to direct output to, you can configure Wind/U to recognize those printers. To configure Wind/U to recognize a printer, you must do the following

1. Define a port, which is an alias for the print command.
   
   
2. Associate the port with the printer's PPD file.
   
   
3. Specify a default printer.
   
   
4. Set printer options.
   
   

Defining a Port

A printer port is an alias for the print command. It is defined in the [ports] section of $HOME/.WindU and appears as part of the Printer Name in the Printer Setup dialog box. For example, the following is the first Printer Name in the Printer Setup dialog box before you make any changes to $HOME/.WindU.

AppleLaserWriter v23.0 PostScript on FILE:

In this Printer Name, FILE: is the port name. Port entries in the [ports] section have the following format.

port=print_command

The print_command sends output to the printer port. For example, if you have two printers: ORION and SIRIUS, your [ports] section may look like the following example.

[ports]
ORION=rsh bandit lp -d ps -t\”$XPDOCNAME\”
SIRIUS=rsh bandit lp -d ps -T pcl5 -t\”$XPDOCNAME\”

In this example, both printers are connected to the system bandit, so the print command is a remote shell command executed on bandit. ORION is a PostScript printer, so the command lp -d ps is executed on bandit to print to ORION. SIRIUS, however, is a PCL5 printer, so the print command executed on bandit to print to SIRIUS is lp -d ps -T pcl5.

If you have a printer connected to your local system, you need to add an entry for it. For the local printer, add an entry similar to the following.

[ports]
ORION=rsh bandit lp -d ps -t\”$XPDOCNAME\”
SIRIUS=rsh bandit lp -d ps -T pcl5 -t\”$XPDOCNAME\”
LOCAL=lp -d ps -t$XPDOCNAME

Your printer port can be any name, except FILE:, which is the only reserved port name. It causes HyperHelp to create a print file formatted specifically for the specified printer type.

You must create an entry in the [ports] section for every printer you want to print to.

To Define a New Port

To define a new port using the Printer Setup dialog box, perform the following steps.

1. To display the Ports dialog box, from the Printer Setup dialog box, click Install, Add Printer, and Define New Port.
   
   
2. Type the port definition in the Edit Port edit box.
   
   
3. Click Add/Replace.
   
   The new port is now included in the list of current port definitions.
   
   
4. Repeat steps 1-3 for each printer you want to print to.
   
   

Note: To create a printer port for each available printer queue on HP700 systems, click the Spooler button in the Ports dialog box. This command creates a default printer port for each available printer queue returned by the lpstat -a command.

To Modify an Existing Port

To modify an existing port using the Printer Setup dialog box, perform the following steps.

1. To display the Ports dialog box, from the Printer Setup dialog box, click Install, Add Printer, and Define New Port.
   
   
2. Select the port you want to modify and edit the port information in the Edit Port edit box.
   
   
3. Click Add/Replace.
   
   The modified port is now included in the list of current port definitions.
   
   

Matching a Printer Type to a Defined Port

After you define a port for each printer, specify the type of printer associated with each port. Device types are listed in the [devices] section of the .WindU file. Each entry in the [devices] section has the following format.

alias=PPD_file driver,port

Note: There must be a space between the PPD_file and driver and a comma between the driver and the port. The following table describes each part of this entry.

Following is an example procedure for configuring three printers.

1. Choose an alias for each printer.
   
   To easily identify the printer you want to use from the Printer Setup dialog box, use these aliases.
   
   
   • HP LaserJet PS
     
     
   • HP LaserJet PCL
     
     
   • QMS PS
     
     

     Note: If you use the Printer Setup dialog box to associate ports and PPD files, you cannot specify a printer alias. You must choose an alias from the predefined list that appears in the Printer Devices list box in the Add Printer dialog box. The corresponding PPD file is already associated with the printer aliases in this list box.

2. Identify the PPD file associated with each of these printers. In this example, the [devices] section of the .WindU file appears as follows.
   
   [devices]
   HP LaserJet PS=HP3SI523 PostScript,ORION
   HP LaserJet PCL=HP4M PCL,SIRIUS
   QMS PS=Q2200523 PostScript,LOCAL
   
   After you add these entries to your .WindU file, the following printer choices are available from the Printer Setup dialog box.
   
   HP LaserJet PS on ORION
   HP LaserJet PCL on SIRIUS
   QMS PS on LOCAL
   
   

To match a printer device to a port using the Printer Setup dialog, perform the following steps.

1. To display the Add Printer dialog box, from the Printer Setup dialog box, click Install and Add Printer.
   
   
2. In the Printer Devices field, select the description that matches the printer you are installing.
   
   If no description matches your printer, contact your printer vendor for a printer description (PPD) file and install it in the $WUHOME/xprinter/ppds directory.
   
   
3. Select the desired port in the Current Port Definitions list box and click Add Selected.
   
   The new printer is now included in the list of currently installed printers.
   
   

To Remove an Installed Printer

To remove a printer device/port combination using the Printer Setup dialog box, perform the following steps.

1. To display the Printer Installation dialog box, from the Printer Setup dialog box, click Install.
   
   
2. In the Currently Installed Printers list box, select the printer you want to remove and click Remove Selected.
   
   

Specifying a Default Printer

After all available printers are configured, you can make one of them the default printer. To specify a default printer in the Printer Setup dialog box, add an entry in the following format to the [windows] section of the .WindU file.

[windows]
device=PPD_file,driver,port

Provide the same information that you used in the [devices] section. Only the format of the entry is different; there is a comma between the PPD_file and the driver instead of a space.

For example, if you want the default printer to be the printer at port ORION, your [windows] section appears as follows.

[windows]
device=HP4L,PostScript,ORION

The printing-related sections of your .WindU file look like the following.

[windows]
device=HP4L,PostScript,ORION

[ports]
ORION=rsh bandit "lp -d ps -t"
SIRUS=rsh bandit "lp -d ps -T pcl5"
LOCAL=lp -d ps

[devices]
HP LaserJet PS=HP4L PostScript,ORION
HP LaserJet PCL=HP4M PCL,SIRIUS
QMS PS=Q2200523 PostScript,LOCAL

Whenever you make and save a change with the Printer Setup dialog box, the changes are written to the .WindU file in your home directory.

In your default .WindU file, the [windows] entry appears as follows.

[windows]
device=NULL,PostScript,FILE:

Because no PPD file is listed (NULL), the default in the Printer Setup dialog box is to print generic PostScript to a file. You can specify the file name and change the type of output to PCL in the Printer Setup dialog box.

To Specify a Default Printer

To specify a default printer using the Printer Setup dialog box, do the following.

1. To display the Options dialog box, from the Printer Setup dialog, click Options.
   
   
2. From the Printer Name drop-down list, select the desired printer and click OK.
   
   
3. Click Save in the Printer Setup dialog box.
   
   

Setting Printer Options

Because printer options vary between printers, use the Printer Setup dialog box to set them. Xprinter reads the PPD file to identify the specific options available for each printer.

1. Display the Printer Setup Dialog box.
   
   
2. Set all fields to the desired values. The following table describes all printer setup fields.
   
   
   
   

   Option	Description
   Output Format	Specify whether to send output to a file or to a printer. If you choose Printer Specific, you can send output to any printer type/port combination configured in your $HOME/.WindU file. If the port is FILE: (as in this example), Xprinter creates an output file specifically for the specified printer type. If you choose Generic (File Only), print output is sent to an Encapsulated PostScript or generic PCL file.
   Printer	Appears only if you select Output Format: Printer Specific. It specifies the name of the default printer to send print output to. Click the Options button to specify a different printer.
   File Name	Appears only if you select Output Format: Generic (File Only). Type the name of the print file to create. To pipe print output to a command, type a! character as the first character, then specify the command to pipe output to. For example, to pipe output to the lp command, enter the following: !lp -d ps.
   EPSF PCL4 PCL5	Appears only if you select Output Format: Generic (File Only). Click this button to display a list of output file types and select the desired type. Available types are EPSF (Encapsulated PostScript), PCL4, and PCL5.
   Orientation	Specify portrait or landscape.
   Scale	To increase the size of the output, specify a value greater than 1.00. To reduce the size, specify a value less than 1.00. For example, a value of 2.00 doubles the size of the output; a value of 0.50 reduces it by half.
   Copies	Specify the number of copies to print.

   
   
   
   
3. To set additional options, such as selecting a new printer or changing the page size, click Options.
   
   
4. Set all options to the desired values.The following table describes all printer options.
   
   
   
   

   Option	Description
   Printer Name	Changes the Printer in the Setup dialog box. Click the down arrow to display a list of configured printers.
   Resolution	Specify printer resolution. Values vary.
   Page Size	Specify paper size. Values vary.
   Paper tray	Specify tray where paper is located. Values vary.

   
   
   
   
5. Click Save to apply your changes and make them the new default values.
   
   

Sending Output to a File

The default $HOME/.WindU file contains many printer devices, including the following.

HP LaserJet 4L PostScript=HP4L PostScript,FILE:
HP LaserJet 4M PCL Cartridge PCL5=HP4M PCL,FILE:

In all of the default entries, the port is FILE:, which is the only reserved port name. If you specify FILE: as the port, Wind/U creates a print file instead of sending output to a printer. When you use a PPD file, you generate PostScript or PCL output that is specific to the printer. If you use Output Format: Generic (File Only), you generate generic Encapsulated PostScript or PCL output.

For example, the HP LaserJet 4L PostScript entry creates a PostScript file that includes the characteristics of the HP 4L PostScript printer. The HP LaserJet 4M PCL entry creates a PCL file that includes the characteristics of the HP LaserJet 4M PCL printer.

You can also print to a file instead of a printer by selecting the Output Format: Generic (file only) option in the Printer Setup dialog box, but doing so creates a generic EPS or PCL print file that does not take advantage of any special characteristics of your particular printer.

Solving Printing Problems

If you have problems printing, use the following hints.

• Start with just printing to a PostScript file. You can use PostScript previewers (on Sun's pageview), to see the file. Adding spooling and PCL support later is easy.
  
  
• Ensure that the $WUHOME/xprinter files are installed correctly.
  
  
• Ensure that you have .WindU in your home directory.
  
  
• Check that the printing sample application works with the configuration you are using with your application.
  
  
• Ensure that there is a PPD file for the printer you are using. Xprinter requires a PPD file that describes the attributes (paper size, resolution, color capabilities, paper trays, and so forth). for each printer device you want to use. Wind/U includes a number of PPD files for common printers; however, these do not represent all supported printers. If you have customer whose printer is not included in the PPD files supplied with Wind/U, try the following.
  
  
  • Contact the printer manufacturer for the PPD file.
    
    
  • Download the PPD file from the Adobe FTP site (ftp.adobe.com:/pub/adobe/PPDfiles).
    
    
  • Use the PPD file for a similar output device.
    
    

If you continue to have problems, submit an SPR to Bristol Technical Support. Be sure to include a copy of your printer output and your .WindU file.