escper 1.1.9 → 1.2.0

data/README.md

@@ -11,9 +11,11 @@ Introduction
 
 Escper is a collection of essential tools that make printing of plain text and images to one or many serial thermal printers easy. Both USB and serial (RS232) printers are supported and detected automatically. Escper is useful for Ruby based Point of Sale systems that want to print receipts or tickets.
 
-While the actual printing is just writing a string to a device node inside of `/dev`, there is some preprocessing necessary. Thermal printers usually have a narrow character set, do not support UTF-8, only ASCII-8BIT. Escper makes it possible to just send UTF-8 text and it does all the conversion work under the covers. For special characters, Escper will map UTF-8 characters to the ASCII-8BIT codes that are actually supported by the currently set codepage on the printer (have a look at the user manual of your printer). The file `lib/escper/codepages.yml` is an example for matching UTF-8 codes to ASCII codes.
+While the actual printing is just writing a string to a device node inside of `/dev`, there is some preprocessing necessary. Thermal printers usually have a narrow character set, do not support UTF-8, only ASCII-8BIT. Escper makes it possible to just conveniently pass an UTF-8 string to the printing method, and it does all the conversion work under the covers. For special characters, Escper will map UTF-8 characters to the ASCII-8BIT codes that are actually supported by the currently set codepage on the printer (have a look at the user manual of your printer). The file `lib/escper/codepages.yml` is an example for matching UTF-8 codes to ASCII codes of the standard codepage of the commonly available Espon and Metapace printers.
 
-Another tricky usecase is where text is mixed with images. Images are transformed into ESCPOS compatible printing data, which is supported by the majority of thermal printers. When mixing text and images, Escper will transform special UTF-8 characters according to the above mentioned codepages.yml file, but leave the image data unchanged.
+Another tricky usecase is where text is mixed with images. Images are transformed into ESCPOS compatible printing data, which is supported by the majority of thermal printers. When mixing text and images in one print 'document', Escper will still transform special UTF-8 characters according to the above mentioned codepages.yml file, but leave the image data raw i.e. unchanged.
+
+Escper only supports printers which support plain data copy to their device node living under `/dev`. Printers for which the Kernel does not create a device node that can be opened as a file or as a Serial Port are not supported. Escper does not care about the styling of the text with special printer commands; it is up to the user to pass those commands as part of the printing string. An exception are images; those are converted to ESCPOS code.
 
 Some Point of Sale systems, especially those for restaurants, have to send tickets to several printers at the same time (e.g. kitchen, bar, etc.). Escper makes this easy. Have a look at the usage examples below.
 
@@ -28,13 +30,11 @@ The source of the image can be a file:
 
     escpos_code = Escper::Img.new('/path/to/test.png', :file).to_s
 
-The source of the image can also be data which is uploaded from a HTML form:
+The source of the image can also be data which is uploaded from a HTML form. Here, the variable `data` is a variable containing the image data of a multipart HTML form:
 
     escpos_code = Escper::Img.new(data.read, :blob).to_s
     
-"Data" is a variable containing the image data of a multipart HTML form.
-    
-Alternatively, the source can be an ImageMagick canvas:
+Alternatively, the image source can also be an ImageMagick canvas:
 
     canvas = Magick::Image.new(512, 128)
     gc = Magick::Draw.new
@@ -50,24 +50,25 @@ Alternatively, the source can be an ImageMagick canvas:
     gc.draw(canvas)
     escpos_code = Escper::Img.new(canvas,:obj).to_s
 
-For optimal visual results, when using a file or a blob, the image should previously be converted to an indexed, black and white 1-bit palette image. In Gimp, click on "Image -> Mode -> Indexed..." and select "Use black and white (1-bit) palette". For dithering, choose "Floyd-Steinberg (reduced color bleeding)". The image size depends on the resolution of the printer. The Escper gem contains a test image in `examples/escper.png`.
+For optimal visual results, when using a file or a blob, the image should previously be converted to an indexed, black and white 1-bit palette image. In Gimp, click on "Image -> Mode -> Indexed..." and select "Use black and white (1-bit) palette". For dithering, choose "Floyd-Steinberg (reduced color bleeding)". The image size depends on the resolution of the printer.
 
 To send an image directly to a thermal receipt printer in just one line:
 
     File.open('/dev/usb/lp0','w') { |f| f.write Escper::Img.new('/path/to/image.png').to_s }
     
-Usecase: Print UTF-8 text to several serial printers at the same time
+    
+Usecase: Print UTF-8 text to several printers at the same time
 ------------
 
-First, create printer objects which are simply containers for data about the printer. If you develop your application in a framework like Rails, you also can use the models from this application instead of creating them from within Escper. The only requirements are that the objects respond to the methods `id`, `name`, `path`, `copies` and `codepage`.
+First, create `VendorPrinter` objects which are simply containers for configuration data about the printer. If you develop your application in a framework like Rails, you also can use the models from the Rails application instead of creating them from within Escper. The only requirements are that the objects respond to the methods `id`, `name`, `path`, `copies`, `codepage` and `baudrate`.
 
     vp1 = Escper::VendorPrinter.new :id => 1, :name => 'Printer 1 USB', :path => '/dev/usb/lp0', :copies => 1
     vp2 = Escper::VendorPrinter.new :id => 2, :name => 'Printer 2 USB', :path => '/dev/usb/lp0', :copies => 1
     vp3 = Escper::VendorPrinter.new :id => 3, :name => 'Printer 3 RS232', :path => '/dev/ttyUSB0', :copies => 1
     
-`id` must be unique numbers which will be needed later during printing. `name` is an arbitrary string which is only used for logging. `path` is the path to a regular file or the device node of the thermal printer which usually lives under `/dev`. Device nodes can be of the type USB or serial (RS232). `copies` are the number of copies of pages that the printer should print. Optionally, you can pass in the key `codepage` which is a number that must correspond to one of the YAML keys in the file `codepages.yml`. By making the `codepage` a parameter of the printer model, it is possible to use several different printers from different manufacturers with different character sets at the same time.
+`id` must be unique integers which will be needed later during printing. `name` is an arbitrary string which is only used for logging. `path` is the path to a regular file or the device node of the thermal printer which usually lives under `/dev`. Device nodes can be of the kinds USB or serial port (RS232). `copies` are the number of duplications of pages that the printer should print. Optionally, you can pass in the key `codepage` which is a number that must correspond to one of the YAML keys in the file `codepages.yml`. By making the `codepage` a parameter of the printer model, it is possible to use several different printers from different manufacturers with different character sets at the same time. `baudrate` is an optional integer to set the speed of the transmission (the default is 9600, this setting is only effective when using RS232 communication).
 
-Next, initialize the printing engine of Escper by passing it an array of the printer objects. It is also possible to pass it a single printer model instead of an array:
+Next, initialize the printing engine of Escper by passing it an array of the VendorPrinter instances. It is also possible to pass a single VendorPrinter instance instead of an Array. As mentioned earlier, you also can pass instances or Arrays of instances of a class that is named differently (e.g. ActiveRecord queries), as longs as it responds to the afore mentioned attributes:
 
     print_engine = Escper::Printer.new 'local', [vp1, vp2, vp3]
     
@@ -116,7 +117,7 @@ Print text and image at the same time:
 
     print_engine.print 1, 'print text and image1 {::escper}image1{:/} and image 2 {::escper}image1{:/} to printer 1', raw_images
     
-Note that the magic tag `{::escper}image_key{:/}` will be replaced by Escper with the image that is stored in the hash `raw_images` with the key `image_key`.
+Note that the magic tag `{::escper}image_key{:/}` will be replaced with the image that is stored in the hash `raw_images` with the key `image_key`.
 
 After printing is done, close the device nodes again:
 
@@ -126,7 +127,7 @@ After printing is done, close the device nodes again:
 Fallback mode
 ----------------------
 
-If a device node is busy or not writable, Escper will create fallback files instead and append the print data to that file. The fallback files will have the name of the printers and will be saved inside of `/tmp`, or, when you include Escper from Rails, in the `tmp` folder of the Rails app source.
+If a device node is busy or not writable, Escper will create fallback files instead and append the print data to that file. The fallback files will have the name of the printers and will by default be saved in `/tmp`, or, when you include Escper from Rails, in the `tmp` folder of the Rails app source.
 
 Configuration
 ----------------------
@@ -139,9 +140,9 @@ You can configure Escper by calling in your project:
       config.safe_device_path = File.join('path', 'to', 'outputdir')
     end
 
-`codepage_file` specifies the path to `codepages.yml`. (for an explanation see above)
+`codepage_file` specifies the path to `codepages.yml`. (for an explanation see above). If not specified, the file `codepages.yml` that is part of this gem distribution will be used.
 
-`use_safe_device_path` can be set to `true` when you are running Escper on a remote server and no actual writes to device nodes should occur. In this case, all print data will be stored in regular files in the path `safe_device_path` with safe file names, which can be further processed or submitted by other programs.
+`use_safe_device_path` can be set to `true` when you are running Escper on a remote server and no actual writes to physical printers should occur. In this case, all print data will be stored in regular files in the path `safe_device_path` with safe/escaped file names, which can be further processed or served by other programs.
     
 Additional Features
 ----------------------
@@ -149,6 +150,20 @@ Additional Features
 For additional features, please study the source code.
 
 
+Application
+----------------------
+
+Escper is actively used in the production-quality Point of Sale products
+
+[SALOR Retail](https://github.com/jasonknight/salor-retail)
+
+and
+
+[SALOR Hospitality](https://github.com/michaelfranzl/SalorHospitality)
+
+and indirectly used by dozens of real stores daily, around the clock, around the world.
+
+
 Contact
 ----------------------
 

data/lib/escper/version.rb

@@ -1,3 +1,3 @@
 module Escper
-  VERSION = "1.1.9"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: escper
 version: !ruby/object:Gem::Version
-  version: 1.1.9
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors: