add README

     1.1 diff -r 57eff547e4f1 -r cf9d239ac1c9 README
     1.2 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.3 +++ b/README	Wed Aug 05 17:10:56 2009 +0100
     1.4 @@ -0,0 +1,137 @@
     1.5 +libptouch: Linux printer driver library for P-Touch label printers
     1.6 +(C) 2009 Philip Pemberton <philpem@philpem.me.uk>.
     1.7 +
     1.8 +
     1.9 +
    1.10 +Table of Contents
    1.11 +=================
    1.12 +  1. What is libptouch?
    1.13 +  2. Supported printers
    1.14 +  3. Building and Using libptouch
    1.15 +  T. TODO, aka Things That Don't Work Yet.
    1.16 +  R. References
    1.17 +
    1.18 +
    1.19 +1. What is libptouch?
    1.20 +=====================
    1.21 +libptouch is a library that allows a user-mode application to print labels
    1.22 +using a Brother P-touch series label printer. The goal of the libptouch
    1.23 +project is to create a driver that will allow any Linux application to
    1.24 +print to a P-touch printer, using a common raster image as a source.
    1.25 +
    1.26 +Brother only release official Linux drivers for a small number of P-touch
    1.27 +printers, and these all rely on the CUPS printing system to function (not to
    1.28 +mention the fact that the print filter is completely closed-source). On top
    1.29 +of the added complexity of having to feed data through CUPS or LPR, the print
    1.30 +quality was actually pretty poor -- the fonts were covered in jagged edges,
    1.31 +and printed barcodes looked like they'd been fed through a blender (needless
    1.32 +to say my PSC 5281 scanner wouldn't read them).
    1.33 +
    1.34 +As a result of this, I started working on a library that could take a number
    1.35 +of Libgd images, and feed them to the P-touch in sequence. On top of that, I
    1.36 +wanted to be able to set printing parameters (that is, turn the auto-cutter
    1.37 +and mirroring options on and off) without having to butcher command lines
    1.38 +and drop to a shell. Finally, I wanted to be able to run my applications as a
    1.39 +(relatively) unprivileged user -- the printing apps should not need to be
    1.40 +'setuid root'.
    1.41 +
    1.42 +So I set to work finding out all I could about the P-touch protocol. It turns
    1.43 +out that the standard mode for my PT-2450DX printer was the so-called "PT-CBP"
    1.44 +mode, and that documentation for this printing protocol had been released for
    1.45 +another printer in the P-touch series, the PT-9500PC[1]. Using the protocol
    1.46 +details in the PT-9500PC documentation, and after many long nights of coding,
    1.47 +lots of cups of tea and much wasted label tape, I created a library that would
    1.48 +eventually be released as libptouch.
    1.49 +
    1.50 +
    1.51 +2. Supported printers
    1.52 +=====================
    1.53 +
    1.54 +NOTE: If you don't see your printer on this list, ask me about adding it.
    1.55 +
    1.56 ++--------------+--------------------------------------------------------------+
    1.57 +|   Printer    | Features                                                     |
    1.58 +|    Model     +----+----+----------------------------------------------------+
    1.59 +|    Number    | S  | AC | HC | PHW | DPI | MTH  | MPH  |                     |
    1.60 ++--------------+----+----+----+-----+-----+------+------+---------------------+
    1.61 +| PT-2450DX    | Y  | Y  |    | 128 | 180 | 24mm | 18mm |                     |
    1.62 ++--------------+----+----+----+-----+-----+-----------------------------------+
    1.63 +
    1.64 +S   = Supported/Tested
    1.65 +        Y = Fully working
    1.66 +        P = Partially working
    1.67 +        ? = Not tested
    1.68 +AC  = Auto Cutter
    1.69 +HC  = Half Cut
    1.70 +MI  = Mirror
    1.71 +PHW = Printhead width (pixels)
    1.72 +DPI = Dots per inch
    1.73 +MTH = Max label tape height (mm)
    1.74 +MPH = Max printing height (mm)
    1.75 +
    1.76 +"Y" = Yes
    1.77 +" " = No
    1.78 +
    1.79 +
    1.80 +3. Building and Using libptouch
    1.81 +===============================
    1.82 +To build libptouch, you will need:
    1.83 +  GNU gcc    version 3.1 or later  (libptouch is tested with gcc 4.3.3)
    1.84 +  GNU make   version 3.80 or later (libptouch is tested with make 3.81)
    1.85 +  libgd      version 2.0 or higher (libptouch is tested with libgd 2.0.36)
    1.86 +
    1.87 +Briefly, this means any common Linux distribution (Debian or RedHat based)
    1.88 +released in 2006 or later should successfully build libptouch. As for other
    1.89 +Unices, or older versions of Linux.... you're on your own.
    1.90 +
    1.91 +On Ubuntu or Debian, the following command will install all the packages
    1.92 +necessary to build libptouch:
    1.93 +  $ sudo apt-get install build-essential libgd2-xpm-dev
    1.94 +
    1.95 +Once you have installed the necessary tools and libraries, you can compile
    1.96 +libptouch by using the following command:
    1.97 +  $ tar -zxf libptouch-$VERSION.tgz
    1.98 +  $ cd libptouch-$VERSION
    1.99 +  $ make
   1.100 +
   1.101 +This will build the libptouch library and documentation from the source code.
   1.102 +
   1.103 +
   1.104 +T. TODO, aka Things That Don't Work Yet.
   1.105 +========================================
   1.106 +  * Printers with printheads that don't have 128 dots will not work. This
   1.107 +    basically means you can't use any printer whose maximum label tape width
   1.108 +    is less than 24mm.
   1.109 +
   1.110 +  * I'd like to implement graphics inversion. Basically, where there is white,
   1.111 +    the printer will print black. This could be useful for printing
   1.112 +    white-on-black labels when you're out of white-on-black tape, or vice versa
   1.113 +    :)
   1.114 +
   1.115 +  * There is no support for serial port printers. At all.
   1.116 +
   1.117 +  * The PT-PC is not, and will likely never be supported, as it uses a
   1.118 +    different printing protocol and can only print bit image graphics on the
   1.119 +    central 3.5mm (!) of the label tape.
   1.120 +
   1.121 +  * The QL-series label printers aren't supported either. I'd love to add
   1.122 +    support for them, but I don't have a QL-series printer to play with. The
   1.123 +    same applies to the rest of the P-touch (PT-series) printers that aren't
   1.124 +    listed as "Supported" in the list above.
   1.125 +
   1.126 +  * Data compression. The later PT-series printers support "Packbits"
   1.127 +    compression of each print line. At the moment, this isn't implemented.
   1.128 +    Instead, a "COPY N BYTES" compression control byte is sent, followed by
   1.129 +    a line of print data. Rinse, repeat.
   1.130 +
   1.131 +  * No option to set the feed amount. I'm not even 100% sure if this works
   1.132 +    on most PT-series printers, but it might be worth implementing. See
   1.133 +    <http://www.undocprint.org/formats/page_description_languages/brother_p-touch>.
   1.134 +
   1.135 +
   1.136 +R. References
   1.137 +=============
   1.138 +1. Brother Industries, Ltd. "PT-9500PC Command Reference, CBP-RASTER Mode
   1.139 +  (PTCBP Mode) Volume" August 29, 2003, version 1.0.
   1.140 +  Available online: http://etc.nkadesign.com/Printers/QL550LabelPrinter
   1.141 +