XPaint Files

About Deskwrite  (version 3.1, August 14, 2021)
===============================================

Deskwrite can be used to simulate an "electronic blackboard" using
a computer and a videoprojector. 

It can also be used as a standalone note taking application. Optionally,
it includes handwriting recognition capabilities. The related utility
dkw2tex will (attempt to) convert your notes into a TeX file.

Although the program is functional with just a standard mouse or a
laptop touchpad, the use of a touchscreen (preferably with a stylus),
or a graphics tablet is almost indispensable; the Android tablets
can also be used as input devices thanks to the GfxTablet+ Android app.

Wacom tablets and some LCD tablets, such as the Boogie Board
RIP/Sync (2012-2015), and the more recent NewYes Archive Sync (2019)
work quite well. User space drivers are available for these.
The corresponding executables 'wcmtd', 'bbtd' and 'nytd' may have
to be set suid (type 'chmod a+s wcmtd bbtd nytd' as root).
Such user space drivers executable are expected to support - or
possibly ignore if this is not needed - some default options that
enable button actions, subpixel rendering, and redirection of
input on a specified window:
  <driver_exec> -subpixel -buttons -wid <X11_window_hexa_value>
(See for instance the code of the newyes tablet driver.)

An alternative program for taking notes is "xournal". Its interface
is a bit simpler and possibly more polished, but deskwrite has
various other capabilities; it is more oriented towards simulating
a blackboard. Deskwrite can easily import PDF presentation files
(such as beamer slides), that can be annotated interactively
during a presentation.

About GfxTablet+
================

GfxTablet+ is an extension of GfxTablet by Richard Hirner (rfc2822),
in other words, it is an Android application to turn an Android tablet
into a virtual graphics tablet attached to a desktop computer, using a
network/wireless IP connection between both devices. It is especially
suited to work with the Samsung Galaxy Note series, but any tablet
that has sufficient graphical resolution should work.

Installation: 
- download GfxTablet+-v1.x.apk on your Android tablet, and install
  the application on it. This may require setting adequately some
  permissions, since GfxTablet+ will need to write data on your sdcard.
- Install networktablet+ and deskwrite (as explained below)
- To open the link between your Android tablet and the Linux 
  desktop/laptop, type as root something like
     networktablet+ -user dupont [-home /home/dupont]
  (adapted of course to your particular setting)
- If you operate in a location that does not have an accessible wireless
  network, you may try to create a wireless hotspot on your tablet or
  on your laptop.

Installation instructions for Deskwrite
=======================================

In order to compile 'deskwrite', you will need the standard development
libraries for X11, and additionally libxft-dev, libpng-dev and libdvipgm
from the dvipgm-1.0 package. The latter is used for TeX input, and has
a number of standard dependencies such as libkpathsea-dev. A TeX
environment is needed, unless DVIPGM linking is disabled.

Optionally, deskwrite can also be linked with two handwriting recognition
packages, namely writepad (for cursive handwriting recognition) and seshat
(for math formula recognition).

You will thus need to install all required development libraries first,
and then, in order,

* dvipgm (optional ; dvipgm has its own dependencies, including
  libfreetype-dev and libkpathsea-dev)

* writepad (optional, requires a C++ compiling environment)

* seshat (optional, requires a C++ compiling environment and the boost
  libraries).

* deskwrite

A lot of dependencies disappear if you do not wish to use dvipgm, writepad
and seshat. Check the first few lines of the 'Makefile' and adjust the
relevant parameters with yes/no.

The fonts/ subdirectory contains some fonts used by default by deskwrite.
You should probably install them if those fonts are not already installed.

The auxiliary program dkw2tex is a command line tool that tries to convert
the handwritten file <my_notes.dkw> into (La)TeX format <my_notes.tex>.
The output will actually become a valid Plain-TeX file if accented
letters are converted to TeX ASCII notation, or a valid LaTeX file
if you add ad hoc header files, including e.g. language and UTF8
input packages.

Usage
=====

Deskwrite has a very large number of command line options that can be used
to tweak most parameters. Almost all of them can also be set at runtime.
Type 'deskwrite -h' to get a list, or better, type F1 within deskwrite
and scroll through the list.

Deskwrite can make use of certain graphics tablets possessing a user space
driver, such as the Improv Boogie Board RIP or Sync 10" and the 
NewYes Sync Archive 10". For instance, in combination with the
NewYes tablet, just type
   deskwrite -tabletdriver "nytd"
where 'nytd' is the NewYes user space tablet driver. The tablet
driver is supposed to provide the appropriate vertical:horizontal
aspect ratio to be used by deskwrite, but you can adopt a different
one by specifying e.g. -da 3:4 after the -tabletdriver option.

Changelog
=========

* February 1, 2017
  First post of version 1.0 on Sourceforge

* February 2, 2017
  Version 1.1 corrects minor issues with math formula recognition

* February 4, 2017
  Version 1.2 brings some improvement in the color management of
  TeX formulas and a new parameter setting that should speed up
  TeX formula recognition

* February 9, 2017
  Version 1.3 corrects a UTF8 conversion issue with the Phatware
  recognizer, when European languages other than English are used.
  The shrink/stretch mode has been improved.

* February 26, 2017
  Version 1.4 improves the selection menu: objects can now be selected
  by specifying their type. A few minor issues have also been fixed.
  The compilation of deskwrite-1.4 requires headers from libraries
  dvipgm-1.1 and seshat-1.2.

* March 9, 2017
  Version 1.5. Minor GUI improvements; cursive handwriting recognition
  should work better - still far from perfect. Use of deskwrite in
  combination with networktablet+ has been fixed (using version 1.1 of
  networktablet+).

* March 29, 2017
  Version 1.6. The deskwrite package now includes 'dkw2tex', a command
  line utility to be used offline, that tries to convert the deskwrite
  handwritten notes into a (La)TeX file, using a combination of the
  writepad library (for ordinary text) and the seshat library
  (for math formula recognition). To this end, a new <box> item has
  been introduced in the deskwrite file format - this means that
  dkw2tex will be able to convert files written by deskwrite v1.6,
  but not by earlier versions.

* April 13, 2017
  Version 1.7. Minor GUI improvements and fixes in the zoom input widget.

* July 25, 2020
  Version 1.8. Many minor issues have been fixed. Deskwrite should now
  work well with ad hoc user space drivers. Drivers for the Boogie Board
  Sync and the NewYes Archive Sync are provided.

* August 6, 2020
  Version 1.9. Deskwrite now has the possibility to open graphics and
  menu/controls in separate windows. This option is set via a new
  command line option -panel 0,s (or any setting including the letter 's').
  This is the default when the option -tabletdriver is set. Generic
  Wacom tablets should now be usable in user space, thanks to wcmtd
  (Wacom tablet driver). This provides in principle more accuracy
  than using the standard X11 driver xf86-wacom.
  A new option -savepdf has been added to save specifically in PDF format,
  and options -blindps -blindpdf are available to convert the vector data
  file *.dkw into postscript of PDF, without opening the GUI windows.

* August 14, 2020
  Version 2.0. Several bugs corrected again. Deskwrite's dkw files now
  use a new enhanced format allowing to draw spline curves or combinations
  of spline curves and polygonal broken lines (more to come: circles,
  ellipse arcs, etc - at the moment, they can just be displayed on screen,
  not yet drawn interactively or printed). The new specification is
    <stroke> n=21 w=624.221 color=#ff0000
    125852 169335
    draw: polygon    
    ...
    129741 186304
    draw: spline 1
    90500.4 211403
    ...
    99691.9 167567
  where n=... is the number of subsequent lines, w=... the linewidth.
  The number 1 after spline means that the spline curve should be
  turned into a smooth closed spline curve (0 is set for an open curve).
  An absence of specification is equivalent to "draw: polygon", thus the
  new format is upward compatible. Any "draw: ?" setting applies to the
  point reached at the previous line (it becomes the new starting point
  of the corresponding piece), and any consecutive points preceding
  another "draw: ?" specification.
  In the above, the first "draw: polygon" is a tautology and could
  be removed. No "draw: ?" specification should appear on the first
  line, which is reserved for the initial point of the path. Other
  possible types include arc, ellipse, n-gon, n-star, vector.
  The last 4 types require 1 or 2 parameters, e.g.
  draw: vector 23 125 (meaning: head angle=23°, head size = 1.25%
  of screen size). These parameters can be set from command line
  options.

* August 27, 2020
  Version 2.1. All features introduced in 2.0 are now fully implemented
  and accessible from the GUI. Exporting to Postscript or PDF should
  also work.

* September 14, 2020
  Version 2.2.
  Deskwrite-2.2 now requires dvipgm-1.2 (if TeX/LaTeX input is used).
  Several bug fixes:
  - option -tex (or -ltx) should now correctly display (La)TeX formulas
  - Latin characters (from iso8859-1) should print correctly in
    the postscript/pdf conversion, as well as (La)TeX formulas.

* October 7, 2020
  Version 2.3.
  Deskwrite can now directly export a deskwrite file into a (La)TeX file
  containing a full description of the figure.
  This only works in combination with *.dvi output and dvips (for a use
  with pdftex or pdflatex, export instead to eps/pdf and call the
  resulting eps/pdf files from the TeX file)
  The geometric procedures have been somewhat extended to allow the
  creation of axis ticks, crosses, circular spots and rings that are
  frequently used to represent points in mathematical figures.

* October 12, 2020
  Version 2.4.
  Support added to export a drawing to TeX with pdftex driver macros
  (rather than dvips). This should be compatible with latex/pdflatex
  by including the output in a latex source file in an appropriate way.

* October 27, 2020
  Version 2.5.
  Support added for drawing dashed and dotted lines. Also the new -snap
  option allows to constrain the pointer to land on a predefined square
  grid when clicking on the canvas. This may help to draw more accurate
  mathematical figures.

* November 3, 2020
  Version 2.6.
  The option -beamer has been improved. It is recommended to install
  mupdf and to compile deskwrite using WITH_MUTOOL = yes. The use of
  mutool improves a lot the way pdf files are displayed (through
  antialiasing), and speeds up the whole process

* November 15, 2020
  Version 2.7.
  Deskwrite should now use versions >= 2.0 of the user space drivers
  nytd, bbtd and wcmtd, which include a much better implementation of
  subpixel rendering, using X11 ClientMessage events.
  There is a new experimental compilation flag  -DWITH_PRESSURE
  that compiles an executable 'deskwritep' allowing the use of stylus
  pressure levels - for those graphics tablets possessing this feature.
  deskwritep's option -usepressure <1,0> enables/disables the use of
  pressure sensitivity (while "plain" deskwrite lacks the option).

* January 9, 2021
  Version 2.8.
  Minor fixes in the spline drawing procedure. This also has the effect of
  improving the compatibility of deskwrite with the VXP editor of xpaint.

* May 18, 2021
  Version 2.9.
  When loading slides for a presentation, a more visible pen cursor is shown
  in the current color. A new option -pencursor allows to set the size of
  the pen cursor. A bash script 'slideshow' has been added, that simplifies
  the input of PDF files - it has been set with the nytd driver (NewYes tablet),
  but can be easily modified to work with Wacom tablets (in that case, replace
  nytd by wcmtd).

* July 29, 2021
  Version 3.0.
  This version introduces to new options -bgimage <file> and -bgrescale 0,1
  to the effect of loading a background image (with or without rescaling).
  JPEG and PNG images are accepted. This can be used to imitate writing
  with chalk on a blackboard.

* August 14, 2021
  Version 3.1.
  Minor cleanups and improvements. The -panel option is now more flexible.