Quick Guide

Quick Guide

Using Barcode Writer in Pure PostScript requires only some basic PostScript knowledge that is easily learned by experimentation. If you do not want to get your hands messy playing with PostScript then you can use one of the project's frontends which hide many of the details.

The best way to get familiar with using the code is to download the monolithic flavour of the latest release and open the barcode_with_sample.ps file with a text editor.

This file consists of the following sections:

• A PostScript language indicator beginning %!PS.
• Comments as lines beginning %.
• A definition for the uk.co.terryburton.bwipp category of named resources.
• A small set of named resource definitions for the renderers which generate the graphical output for the symbols, delimited by % --BEGIN RENDERER ...-- and % --END RENDERER ...--.
• A large set of named resource definitions for the encoders which convert the input into a data structure suitable for printing using a PostScript renderer or importing into a frontend application, delimited by % --BEGIN ENCODER ...-- and % --END ENCODER ...--.
• A set of sample barcode invocations delimited by % --BEGIN SAMPLE-- and % --END SAMPLE--.

This is one example from the samples:

150 750 moveto (0123456789) (includetext height=0.75)
/interleaved2of5 /uk.co.terryburton.bwipp findresource exec

The meaning of each component of the invocation is as follows:

150 750 moveto             % The position of the symbol on the canvas
(0123456789)               % The data field: Data content represented by the symbol
(includetext height=0.75)  % The options field: Properties of the symbol
/interleaved2of5           % The type of barcode, often called the "symbology"
/uk.co.terryburton.bwipp findresource exec  % A call to plot the symbol on the canvas

The acceptable contents of the data field varies between symbologies as defined in the symbology reference.

The acceptable contents of the options field is for the most part common across all of the symbologies as defined in the options reference, however encoder-specific options do exist in many cases and the default values of options vary across symbologies.

Using the references mentioned above you should now be able to experiment by carefully amending the sample section of the file and observing the effect on the graphical output.

You will want to view the result of your changes regularly (since bugs may be hard to track down once introduced) either by using a software PostScript interpreter alongside a viewer or by sending the file to a PostScript-enabled printer. Alternatively you can use the web-based generator.

• GhostScript is an open source PostScript interpreter that is available for both Windows and Linux.
• Adobe Distiller is a commercial PostScript interpreter that is available for Windows and macOS.
• gsview is a viewer for PostScript files on Windows which requires that GhostScript be installed.
• gv is a viewer for PostScript files on Linux which requires that GhostScript be installed.
• The Preview application on macOS is able to view PostScript files.
• Most laser printers have native support for PostScript. Look for either Adobe PostScript Level 2 or Adobe PostScript 3 compatibility.
• CUPS, the Common Unix Printing System, adds PostScript support for non-PostScript printers by filtering PostScript documents through GhostScript.

To directly print a file to an installed, PostScript-enabled printer in Windows by printer name use the following command:

PRINT [/D:device] barcode_with_sample.ps

Alternatively for a printer attached directly to the first parallel port:

COPY /B barcode_with_sample.ps LPT1:

To directly print a file to a PostScript-enabled printer in Linux use the following command:

lpr -Pdevice -o raw barcode_with_sample.ps

To convert a file to PNG format using GhostScript use a variant of the following command:

gs -dBATCH -dSAFER -sDEVICE=png16m -dGraphicsAlphaBits=1 -dTextAlphaBits=4 -sOutputFile=out.png

Once you are comfortable with amending the barcode_with_sample.ps file you may want to simplify the file by removing definitions for barcode formats that you do not require bearing in mind the following points:

• You need only include the named resource definitions for the symbologies of the symbols that you are actually intending to create and must include any dependencies as specified in the resource file by the % --REQUIRES ... metadata. Examining the contents of the PS files created by the web-based generator at https://the-burtons.xyz/barcode-generator/ illustrates this point. If you have downloaded the source distribution of BWIPP you can create a standalone file containing only the resources required for a particular symbology by running something like make build/standalone/code39.ps or make build/standalone_package/code39.ps.
• If you intend to create an application whose purpose is to generate documents containing a variety of barcodes it is suggested that you start with the monolithic barcode.ps file and use the % --BEGIN/END ENCODER ...-- and % --BEGIN/END RENDERER ...-- delimiters to extract the relevant named resource definitions into your documents. This will allow you to simply update your project to the latest version of the BWIPP resource by just replacing your barcode.ps with the latest version.
• BWIPP includes a C library with bindings for various languages specifically for this purpose.
• More information is available in the Developer Notes.