Merge pull request #44 from mtking2/docs

Update README & add more docs

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+## Contributing
+
+Check [open issues](https://github.com/bbulpett/zebra-zpl/issues) for things that need work.  
+Also check any [open pull requests](https://github.com/bbulpett/zebra-zpl/pulls) to make sure any changes you want to make haven't already been made by someone else.
+
+### Fork & clone the repository
+
+```
+git clone [email protected]:<your-username>/zebra-zpl.git
+cd zebra-zpl
+git remote add upstream [email protected]:bbulpett/zebra-zpl.git
+bundle install
+```
+
+Then check out a working branch:
+
+```
+git checkout -b <my-working-branch>
+```
+
+### Write tests
+
+This project uses `rspec`. After writing your tests, you can run tests with the following command:
+
+`bundle exec rspec`
+
+
+### Write code
+
+Write your code to make your tests pass.
+
+### Commit & Push your changes
+
+Commit and push your changes to your working branch.
+
+```
+git commit -am 'Add some feature'
+git push origin <my-working-branch>
+```
+
+### Open a pull request
+
+Open a pull request against upstream master and your working branch. Give a brief description of what your PR does and explain what the code changes do.
+
+Thank you!

README.md

@@ -1,11 +1,28 @@
-#### This is a gem based on a terrific older gem by Cassio Marques. Although the new printers are mostly compatible with old Eltron (Epl) code, my needs require many of the new Zebra (ZPL) functions.
-
 # Zebra::Zpl
 
-### ToDo: Update documentation with instructions for new features such as font sizing, margins, and text alignment
+[![gem](https://img.shields.io/gem/v/zebra-zpl?color=orange)](https://rubygems.org/gems/zebra-zpl)
+[![downloads](https://img.shields.io/gem/dt/zebra-zpl?color=brightgreen)](https://rubygems.org/gems/zebra-zpl)
 
 Zebra::Zpl offers a Ruby DSL to design and print labels using the ZPL programming language.
 
+## Contents
+
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Building Labels](#building-labels)
+    - [Printing Labels](#printing-the-labels)
+    - [Elements](#available-elements)
+      - [Text](#text)
+      - [Barcodes](#barcodes)
+      - [QR Codes](#qr-codes)
+      - [Boxes](#boxes)
+    - [Options](#options)
+      - [Rotation](#elements-rotation)
+      - [Justification](#elements-justification)
+  - [Contributing](#contributing)
+  - [References](#references)
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -14,11 +31,11 @@ Add this line to your application's Gemfile:
 
 And then execute:
 
-    $ bundle
+    bundle install
 
 Or install it yourself as:
 
-    $ gem install zebra-zpl
+    gem install zebra-zpl
 
 ## Usage
 
@@ -34,78 +51,67 @@ You create new labels with an instance of the `Zebra::Zpl::Label` class. It acce
 
 With a label, you can start adding elements to it:
 
-	label = Zebra::Zpl::Label.new :print_speed => 3
-	text  = Zebra::Zpl::Text.new :data => "Hello, printer!", :position => [100, 100], :font_size => Zebra::Zpl::FontSize::SIZE_2
-	label << text
+```ruby
+label = Zebra::Zpl::Label.new print_speed: 3
+text  = Zebra::Zpl::Text.new(
+  data:       "Hello, printer!",
+  position:   [100, 100],
+  font_size:  Zebra::Zpl::FontSize::SIZE_2
+)
+label << text
+```
 
 You can add as many elements as you want.
 
 ### Printing the labels
 
 You need to have your printer visible to CUPS (or shared on the network in Windows). Once your printer is configured and you know its name on CUPS (or the Windows shared printer name), you can send the labels to the printer using a `Zebra::PrintJob` instance.
 
-	label = Zebra::Zpl::Label.new(
-	  :width         => 200,
-	  :length        => 200,
-	  :print_speed   => 3
-	)
+```ruby
+label = Zebra::Zpl::Label.new(
+  width:        200,
+  length:       200,
+  print_speed:  3
+)
+
 
+barcode = Zebra::Zpl::Barcode.new(
+  data:                       '12345678',
+  position:                   [50, 50],
+  height:                     50,
+  print_human_readable_code:  true,
+  narrow_bar_width:           4,
+  wide_bar_width:             8,
+  type:                       Zebra::Zpl::BarcodeType::CODE_128_AUTO
+)
 
-	barcode = Zebra::Zpl::Barcode.new(
-	  :data                      => "12345678",
-	  :position                  => [50, 50],
-	  :height                    => 50,
-	  :print_human_readable_code => true,
-	  :narrow_bar_width          => 4,
-	  :wide_bar_width            => 8,
-	  :type                      => Zebra::Zpl::BarcodeType::CODE_128_AUTO
-	)
+label << barcode
 
-	label << barcode
+print_job = Zebra::PrintJob.new '<your-printer-name-on-cups/windows-shared-printer-name>'
 
-	print_job = Zebra::PrintJob.new "<your-printer-name-on-cups/windows-shared-printer-name>"
+ip = '<IP/Host where the print queue lives>'  # can use 'localhost', '127.0.0.1', or '0.0.0.0' for local machine
 
-	print_job.print label
+print_job.print label, ip
+```
 
-This will persist the label contents to a tempfile (using Ruby's tempfile core library) and copy the file to the printer using either `lpr -P <your-printer-name-on-cups> -o raw <path-to-the-temp-file>` (if you're on Mac OSX) or `lp -d <your-printer-name-on-cups> -o raw <path-to-the-tempfile>` (if you're on Linux). All the tempfile creation/path resolution, as well as which command has to be used, are handled by the `PrintJob` class.
+This will persist the label contents to a tempfile (using Ruby's tempfile core library) and copy the file to the printer using either `rlpr -H <hostname/ip> -P <your-printer-name-on-cups> -o <path-to-the-temp-file>` (for Windows systems, see [section](#printing-directly-to-windows-lpd) below) or `lp -h <hostname/ip> -d <your-printer-name-on-cups> -o raw <path-to-the-tempfile>` (for Unix systems). All the tempfile creation/path resolution, as well as which command has to be used, are handled by the `PrintJob` class.
 
-### Printing to directly to Windows LPD
+#### Printing directly to Windows LPD
 This gem also supports printing directly to shared printer on Windows using LPD.
 In order to print directly to a LPD on a Windows machine you need two things:
 - [rlpr](http://manpages.ubuntu.com/manpages/xenial/man1/rlpr.1.html) installed on the (UNIX) system running your app that uses this gem.<sup>[1](#fn1)</sup>
 - LPD Print Service and LPR Port Monitor features enabled on the Windows machine.<sup>[2](#fn2)</sup>
 
 <p align="center">
-<img align="center" src="http://i.imgur.com/3CWkEWU.png" style="height: 250px"/>
+<img align="center" src="http://i.imgur.com/3CWkEWU.png" height="300px"/>
 <p/>
 
 <hr/>
 
-<a name="fn1">1</a>. On a distro such as Ubuntu simply do: `sudo apt-get install rlpr`  
-If using OSX then you will have to manually build it from source and add it to your `$PATH` environment variable.  
-
-<a name="fn2">2</a>. The printer name that you pass in must correspond with the **shared printer name** on the Windows machine.
-
-### Printing QR codes
-
-    label = Zebra::Zpl::Label.new(
-      :width=>350,
-      :length=>250,
-      :print_speed=>3
-    )
-
-    qrcode = Zebra::Zpl::Qrcode.new(
-      :data=>"www.github.com",
-      :position=>[50,10],
-      :scale_factor=>3,
-      :correction_level=>"H"
-    )
-
-    label << qrcode
+<sup><a name="fn1">1</a>. On a distro such as Ubuntu simply do: `sudo apt-get install rlpr`  
+If using OSX then you will have to manually build it from source and add it to your `$PATH` environment variable.<sup/>
 
-    print_job = Zebra::PrintJob.new "your-qr-printer-name-on-cups"
-
-    print_job.print label
+<sup><a name="fn2">2</a>. The printer name that you pass in must correspond with the **shared printer name** on the Windows machine.</sup>
 
 ### Available elements
 
@@ -154,14 +160,55 @@ The available barcode types are:
 You can create QR Codes elements to print using instances of the `Zebra::Zpl::Qrcode` class. It accepts the following options:
 
 * `position`: An array with the coordinates to place the QR code, in dots.
-* `scale factor`: Crucial variable of the QR codes's size. Accepted values: 1-99.
-* `error correction level`: Algorithm enables reading damaged QR codes. There are four error correction levels: L - 7% of codewords can be restored, M - 15% can be restored, Q - 25% can be restored, H - 30% can be restored.
+* `scale_factor`: Crucial variable of the QR codes's size. Accepted values: 1-99.
+* `correction_level`: Algorithm enables reading damaged QR codes. There are four error correction levels: L - 7% of codewords can be restored, M - 15% can be restored, Q - 25% can be restored, H - 30% can be restored.
+
+##### Printing QR codes
+
+```ruby
+label = Zebra::Zpl::Label.new(
+  width:        350,
+  length:       250,
+  print_speed:  3
+)
+
+qrcode = Zebra::Zpl::Qrcode.new(
+  data:             'www.github.com',
+  position:         [50,10],
+  scale_factor:     3,
+  correction_level: 'H'
+)
+
+label << qrcode
+
+print_job = Zebra::PrintJob.new '<your-qr-printer-name-on-cups>'
+
+print_job.print label, '<hostname>'
+```
 
 #### Boxes
 
 You can draw boxes in your labels:
 
-	box = Zebra::Zpl::Box.new :position => [20, 20], :end_position => [100, 100], :line_thickness => 39
+* `position`: An array with the coordinates to place the QR code, in dots.
+* `box_width`: The width of the box in dots
+* `box_height`: The height of the box in dots
+* `color`: The color if the lines. `B` for black, `W` for white.
+* `line_thickness`: The thickness of the border in dots
+* `rounding_degree`: The degree which to round the corners. (0-8)
+
+```ruby
+box = Zebra::Zpl::Box.new(
+  position: [20,20],
+  box_width: 5,
+  box_height: 4,
+  color: 'B',
+  line_thickness: 3,
+  rounding_degree: 6
+)
+```
+
+### Options
 
 #### Elements Rotation
 
@@ -181,12 +228,11 @@ There are four ZPL-supported `:Justification` parameters. "LEFT" (left-justified
 * `Zebra::Zpl::Justification::CENTER` ~ centered
 * `Zebra::Zpl::Justification::JUSTIFIED` ~ full-width-justifed _(YMMV)_
 
+## Contributing
 
+See [CONTRIBUTING.md](CONTRIBUTING.md)
 
-## Contributing
+## References
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+###### This is a gem based on a terrific older gem by Cassio Marques. Although the new printers are mostly compatible with old Eltron (Epl) code, our needs require many of the new Zebra (ZPL) functions.
+* [Zebra Technologies Corporation, _"ZPL II Programming Guide."_ 2019 PDF](https://www.zebra.com/content/dam/zebra/manuals/printers/common/programming/zpl-zbi2-pm-en.pdf)