Moved code and documentation from landfill to tidy repository.

1 files changed, 119 insertions, 2 deletions

diff --git a/README.md b/README.md
index 4cef0ba..f284947 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,119 @@
-# rastertoql570
-CUPS driver and pseudo-library for the QL-570 label printer.
+Motivation                                                         {#mainpage}
+----------
+
+I had some issues with the driver from the vendor. I figured that I need to
+have some clue about what is going on in order to do something about that. I
+ended up writing a driver, oops.
+
+
+What is the relation to `ptouch-driver`?
+----------------------------------------
+
+As far as I understand, `ptouch-driver` is based on the reverse engineered
+protocol. The `rastertoql570` is based on the protocol specification (much)
+later released by the vendor. The `ptouch-driver` is far more complete
+with regards to the surroundings, methinks.
+
+
+Documentation
+-------------
+
+The files generated by Doxygen can be viewed here:
+
+http://static.xenoworld.de/docs/rastertoql570
+
+
+What has been tested?
+---------------------
+
+Right now, _only 62mm continuous labels have been tested_.
+
+
+How do I use this?
+------------------
+
+Everything is a bit crude right now. First, you need GCC and the CUPS
+development libraries (the package might be called `cups-devel` or something
+similar). The driver needs the libraries `cups` and `cupsimage`. Run `make`
+in the `src/` directory.
+
+After building the driver, you end up with a file `rastertoql570` (in the
+project's root directory), you have to put this file in the CUPS filters
+directory, (e.g. `/usr/lib/cups/filter/`).  After that you can just click
+through the CUPS printer installation with your favourite tool or through the
+interface at http://localhost:631/. When you reach the step to provide a
+PPD-file, use the `ppd-file.ppd` in the project's root directory.
+
+It should now be possible to print labels. Be aware that, regardless of the
+tool, you should create a custom document with the dimensions you want. If you
+use, for example, gLabels, create a 12.7mm by 62mm label and include some 1mm
+margins. If you want to print smaller labels, try with a 6.35mm x 62mm label,
+but *remember to set the resolution to 600DPI in that case*.
+
+
+How do I use the provided files to directly drive the printer?
+--------------------------------------------------------------
+
+This assumes that, if you connect the printer to your computer via USB, some
+magic configures it as a printer and provides you with a device such as
+`/dev/usb/lp0`. On two of my machines that ‘just worked’™. Given the right
+permissions you can simply open this file and write to it.
+
+
+Printing a couple of black lines is as simple as this:
+
+~~~~~~~~~~~~~{.c}
+#include "ql570.h"
+
+int main()
+{
+	FILE *device = fopen("/dev/usb/lp0", "wb");
+	ql_status status = {0};
+	ql_print_info print_info = { .raster_number[0] = 150 };
+	uint8_t buffer[90];
+
+	ql_init(false, device);
+	ql_status_request(device);
+	ql_status_read(&status, device);
+	ql_page_start(&print_info, device);
+	ql_set_extended_options(true, false, device);
+	
+	for (int i = 0; i < 150; i++) {
+		memset(buffer, i % 5 == 0 ? 0xFF : 0x00, 90);
+		buffer[0] = 0x00;
+		buffer[1] = 0x00;
+		ql_raster(90, buffer, device);
+	}
+	
+	ql_raster_end(90, device);
+	ql_page_end(true, device);
+	fclose(device);
+}
+~~~~~~~~~~~~~
+
+The fully commented example kann be found in `src/examples/minimal.c`.
+
+If you need some quick and dirty way to print something meaningful on a label,
+use GIMP to create a 720x150 pixel image and export it later as XBM. These are
+simple C files, the structure is pretty self-explanatory.
+
+TODO: Provide example for this, include how to mirror the images...
+
+
+Stuff to be done
+----------------
+
+* Tell the vendor about unclear or wrong information in the specification.
+* Test with other media types.
+* Try to support other printers in the QL series.
+* Maybe use CMake.
+* Improve overview document.
+* There are a couple of nanosleep-calls and the 100ms or so waiting time are
+  completely arbitrary.
+* Currently arguments to the program are ignored. Ideally a help should be
+  printed, and some parameters should be used.
+* Handle SIGTERM.
+* Walk through TODOs in the code.
+* Improve documentation with regards to optional features.
+* Show some care for endianess.
+* Improve the PPD-file, this hasn't received much love.