Changeset 7 in projects

Timestamp:

Jul 19, 2008, 10:34:23 PM (15 years ago)

Author:

sven

Message:

Completed/more accurate documentation.

Files:

• README.txt (modified) (1 diff)
• daten/README.txt (added)
• puncher/README.txt (modified) (1 diff)
• visualisator/README.txt (modified) (1 diff)
• web-frontend/README.txt (modified) (1 diff)

README.txt

@@ -15 +15 @@
    All programs in this project shall be published according to the
    GNU General Public License (GPL), if there are no license information
-   in the particular files.
+   in the particular files. Every directory contains a file called
+   "README.txt" which contains further information about the contents
+   and the license conditions from that subproject.
 
    Many programs or comments, respectively, are written in German, because
    technikum29.de is a german organisation. If you want to collaborate or
-   understand the programs, feel free to mail me (technikum29.de@sven;
+   understand these programs, feel free to mail me (technikum29.de@sven;
    read it the other way around).
+
+   +--------------------------------------------------------------------+
+   |       An overview over the Paper Tape Project subprojects          |
+   +--------------------------------------------------------------------+
+   | perl-tools        | Some tools written in perl to manage binary    |
+   |                   | data, write paper tape ASCII art, print        |
+   |                   | labeled paper tapes, parse ASCII number files, |
+   |                   | etc.                                           |
+   +-------------------+------------------------------------------------+
+   | userspace-driver  | The Linux ppdev userspace driver for the FACIT |
+   |                   | paper tape puncher, written in C, with some    |
+   |                   | C utulity programs and a perl frontend.        |
+   +-------------------+------------------------------------------------+
+   | reader            | A Linux ppdev userspace reader for the         |
+   |                   | GILMETTI paper tape reader, written in C and   |
+   |                   | based on the userspace-driver.                 |
+   +-------------------+------------------------------------------------+
+   | puncher           | A new try for the userspace-driver from the    |
+   |                   | scratch which strictly seperates between       |
+   |                   | platform-dependent backends and platform-      |
+   |                   | independent frontends. In this way we want to  |
+   |                   | program a Windows driver and a universal,      |
+   |                   | simple-to-use GTK frontend                     |
+   +-------------------+------------------------------------------------+
+   | schriften         | Several fonts which can be used to label paper |
+   |                   | tapes. These fonts are usually implemented as  |
+   |                   | Perl scripts.                                  |
+   +-------------------+------------------------------------------------+
+   | visualisator      | Draw virtual paper tapes on computer screens   |
+   |                   | or in PNG or SVG files. A project written in C |
+   |                   | which uses Cairo and GTK.                      |
+   +-------------------+------------------------------------------------+
+   | web-frontend      | A web frontend for the papertape visualisator, |
+   |                   | written in PHP and JavaScript (AJAX).          |
+   +-------------------+------------------------------------------------+
+   | daten             | Some data and paper tape files which contain   |
+   |                   | NCR machine codes. About 40 files are written  |
+   |                   | by Udo, whereas more than one dozen of files   |
+   |                   | were read in with the paper tape reader.       |
+   +-------------------+------------------------------------------------+
+
 
    Sven; 05.05.2008, 19.07.2008
 
-   You can read much more about the projects at:
+   You can read more about the projects at:
      * http://privat.technikum29.de/svens-projekte/Lochstreifen
      * http://dev.technikum29.de/wiki/Projekte/Lochstreifen
-
-   I'll present you now our subprojects / subdirectories, but you can read
-   more about them in the particular README.txt files in the directories.
-
-   main subprojects:
-
-   1. The Perl Tools
-   2. Userspace punch driver (`userspace-driver')
-   3. The User space paper tape reader (`reader')
-   4. The Paper Tape Visualisation project
-
-
-
-

puncher/README.txt

@@ -1 +1 @@
  
- The Paper Tape Project -- Punching
- ==================================
+ The Paper Tape Project -- Punching subsystem
+ ============================================
  
- The punching system consists of platform independent frontend programs and
+ The punching subsystem consists of platform independent frontend programs and
  platform dependent backend library calls.
 

visualisator/README.txt

@@ -11 +11 @@
    widget, respectively.
 
-   An overview about the files:
+   LOCHSTREIFEN cairo drawing routines
+   -----------------------------------
+   The files lochstreifen.c and lochstreifen.h implement the
+   drawing of paper tapes by using the cairo graphics library.
+   These routines only need cairo, so they can be compiled
+   by using `pkg-config --cflags --libs cairo`. They do not
+   need neither GTK nor Glib.
+   The routines only implement the drawing routines - the
+   cairo object (cairo_t) must be given from the implementing
+   programs. In this way you have full freedom to choose a
+   cairo surface -- among others PNG, SVG, PDF, ...).
+   See lochstreifen.h for the structure of the object
+   `LOCHSTREIFEN'. See lochstreifen.c for help with the usage
+   of the functions.
 
-   * lochstreifen.c, lochstreifen.h: The low level cairo
-     drawing routines. Export a LOCHSTREIFEN object which can
-     be used by other programs, e.g:
+   Features:
+   * Lightweight object system, e.g:
+       LOCHSTREIFEN *papertape = lochstreifen_new();
+       printf( "%d", lochstreifen_get_width(papertape) );
+       lochstreifen_set_d(papertape, 42);
+       int dir = lochstreifen_get_orientation(papertape);
+       lochstreifen_draw(papertape, cairo_context);
+       // ...
+   * Everything is configurable -- e.g. geometrical settings
+     like the distance of byte rows, bit columns, feed hole,
+     diameter of the holes, margins and paddings from the
+     paper, etc.
+   * Papertape can easily be rotated and flipped horizontically
+     or vertically. Even affine matrices can be defined --
+     you can use the full power of cairo.
+   * All colors can be set directly, all objects can be
+     said to be skipped in the painting process.
+   * The paper tape data can be served in a byte array or
+     read from a file
+   * Bytes or arrays of bytes can be highlighted with special
+     user-defined colors.
+   * There are functions to transform coordinates to bytes
+     and vice versa for GUI support.
+   * The painting process can actually skip bytes and therefore
+     only paint areas, which is also good for GUI support.
+   * Thanks to cairo and C all painting operations are handled
+     very fast and the output is always high quality.
 
-   * gtkpapertape.c, gtkpapertape.h: A GTK widget which
-     implements the LOCHSTREIFEN object to display paper
-     tapes on computer displays. It can be used in GTK programs
-     directly.
+   GtkPaperTape
+   ------------
+   The files gtkpapertape.c and gtkpapertape.h implement a
+   GTK widget which uses the LOCHSTREIFEN object to display
+   paper tapes on computer displays. It can be used in GTK
+   programs directly and serves dozens of features to control
+   the behaviour and look of the paper tape directly. It is
+   even capable of displaying animations, reacting on mouse
+   movements, intelligent scrolling, byte highlighting, etc.
 
-   * gtk.c: An exemplar GTK program which displays the
-     GtkPaperTape widget in a window.
+   Features:
+   * Nice GTK/Glib like object oriented interface:
+       GtkPaperTape *papertape = gtk_paper_tape_new(mainwindow);
+       gtk_paper_tape_menu_view(papertape, menu);
+       gtk_paper_tape_menu_colors(papertape, menu);
+       gtk_paper_tape_get_whole_box(papertape);
+       // ...
+   * Scrollable widget: Thus, it is possible to zoom the
+     papertape to fill out the complete monitor or to zoom
+     out so you can e.g. read a labeled paper tape.
+   * Very big files can be displayed very performant because
+     only the neccessary regions of the paper tape are
+     redrawn (very big = many MB or even GB)
+   * The widget even serves an optional statusbar on which
+     status informations are printed (like zoom level)
+   * Mouse movements are catched, thus the statusbar can
+     print up-to-date information about the region on wich
+     the mouse cursor resides.
+   * Several menus are provided by this widget:
+     * Export: Display dialogs to export papertape with the
+       current settings to a SVG or PNG file
+     * View: A menu to zoom the papertape, fit it to the window
+       size or display it in real life size (DPI calculation),
+       rotate or flip it or fix the number of virtual null bytes
+       which are added at the beginning/end of the paper tape
+     * Colors: The colors of all components are displayed and
+       can be changed interactively.
+   * Regions can be highlighted, as an frontend for the
+     LOCHSTREIFEN widget.
 
-   * cli.c: A command line program which gives a direct
-     command line interface to the LOCHSTREIFEN object.
+   Exemplar GtkPaperTape implementation: gtk.c
+   -------------------------------------------
+   The file gtk.c shows the GtkPaperTape in a window. It even
+   handles some arguments and can read up data from stdin.
+
+   Command Line Interface to the LOCHSTREIFEN
+   ------------------------------------------
+   The file cli.c provides a direct command line interface to
+   the LOCHSTREIFEN object. Thus you can use the LOCHSTREIFEN
+   drawing routines from any other program.
+
+   Features:
+   * powerful parameter set to control the result in every
+     detail (test it: ./cli --help)
+   * Unix philosophy: Simple usage, can read in data from
+     stdin, can put out result (SVG/PNG) on stdout
+
+   Web frontend
+   ------------
+   We actually have developed a web frontend in PHP which uses
+   the command line interface to generate the results. It
+   recieves the user input by an huge HTML form. Using a lot
+   of AJAX magic, it even caches already created images and
+   creates reports which contain the input data and all
+   settings and which are finally available for the client.
+   To avoid denial of service attacks (DoS), the PHP frontend
+   will deny creating paper tapes if the input file exceeds
+   some MB because the resulting file will be very big
+   (most web browsers reject rendering such big files which are,
+   for example, 400.000px in width).
+   See ../web-frontend/ for the sources and another README.txt.
+
+
 
    See more descriptions and copyright information in the
    accordant .c and .h files.
 
-   Sven Köppel, 19.07.2008 19:30
+   Sven Köppel, 19.07.2008

web-frontend/README.txt

@@ -8 +8 @@
    huge). Like all the visualisation programs, it is highly
    configurable (every detail you can change at the LOCHSTREIFEN
-   object can be changed in the HTML formula). Thus the
+   object can be changed in the HTML form). Thus the
    HTML <form> is quite complex, but very friendly to DAUs
    (a german expression for "PEBKAC") due to the ability to fold
-   the huge formular. It should be running stable but hasn't
+   the huge form. It should be running stable but hasn't
    really been tested so far. Thanks to caching every generated image
    it should even stand very much rendering requests.