From ece65f3e9d935ad4ca0b6f9d626288908c2ad59e Mon Sep 17 00:00:00 2001
From: auroux
+ Version 0.2
+
+ Xournal is an application for notetaking, sketching, keeping
+ a journal using a stylus. It is free software (GNU GPL) and runs
+ on Linux (recent distributions) and other GTK+/Gnome platforms.
+ It is similar to Microsoft Windows Journal or
+ to other alternatives such as
+ Jarnal
+ and Gournal.
+
+Xournal can be downloaded at
+http://math.mit.edu/~auroux/software/xournal/
+
+ Xournal aims to provide superior graphical quality (subpixel resolution) and overall
+ functionality; however it lacks the collaborative features of Jarnal.
+ Since Xournal is still in its early development stages, it may not
+ be fully stable, and some features have not been implemented yet
+ (in particular, freeform selection and PDF backgrounds are missing).
+
+
+ Xournal User's Manual
+
+
+Table of contents
+
+ Xournal's user interface is (hopefully) intuitive, and if you don't run
+ into installation or
+ tablet calibration issues, you'll
+ probably be able to start taking notes without referring to this manual.
+
+ Here is a screenshot of the user interface (click to enlarge):
+
+ + + +
++Refer the next few sections of this manual for more information about +the various functionalities. +
++The pen is the default drawing tool in Xournal. It comes in a variety +of colors (see the color toolbar buttons and the Color submenu of the +Tools menu) and thicknesses (see the +thickness toolbar buttons and +the Pen Options submenu of the Tools menu). +
+
+The eraser lets you erase what you have drawn. If your tablet's stylus
+has an eraser tip, and if the XInput extensions are enabled, the eraser
+will be automatically selected when drawing with the eraser tip.
+Another possibility is to enable the "Emulate Eraser" option in the Options
+menu, which lets you use button 2 or 3 on the stylus (mouse middle or right button)
+as an eraser.
+The eraser comes in three different thicknesses (selected using the
+thickness toolbar buttons),
+and can operate in three different modes (Eraser Options submenu of
+the Tools menu):
+
+ Like the pen, the highlighter comes in a variety of colors (the default + is yellow) and thicknesses. Use the color and thickness toolbar buttons + to change these settings. +
++ The ruler is not a tool by itself, but rather a special operating mode + of the pen and highlighter tools. When it is enabled, these tools paint + line segments instead of curvy strokes. For simplicity, selecting the + ruler when not in pen or highlighter mode automatically selects the pen. +
+
+ Each drawing tool (pen, eraser, highlighter) has a default setting
+ (color, thickness, ...) associated to it.
+ The "Default Pen", "Default Eraser", and "Default Highlighter" entries of
+ the Tools menu select the appropriate tool and reset its settings to
+ the defaults. The toolbar also includes a "Default" button which
+ resets the currently selected drawing tool to its default settings,
+ and a "Default Pen" button.
+ The "Set As Default" entry of the Tools menu takes the current settings
+ of the currently selected drawing tool and makes them the new default.
+
+ These three buttons control the thickness of the current drawing tool + (pen, eraser, or highlighter). The thickness can also be adjusted using + the appropriate sub-menu of the Tools menu. +
++ This tool lets you select a rectangular region of the current layer. + All the strokes which are entirely contained within the rectangular region + are selected. + The selection can be moved within its page by clicking inside the + selection rectangle and dragging the cursor. +
++ The selection can be cut, duplicated, etc. (including to a different page + or to a different journal) using the copy-paste toolbar buttons or the + corresponding entries of the Edit menu. +
++ This tool lets you insert or remove vertical space within the page: + all the items of the current layer which lie entirely between the cursor + position and the end of the page are moved up or down. +
++ Note that the background, and items on other layers, are not affected. + Also, if you insert too much vertical space, some items may fall below + the bottom of the page and become invisible. These items are not lost: + to retrieve them, either use + the vertical space tool again to remove the excess vertical + space, or change the page height to an appropriate value (using the + "Paper Size" entry in the Journal menu). +
+
+ All operations performed on the currently open journal (drawing, erasing,
+ cut-and-paste; adding, deleting, and reformatting pages; etc.) can be
+ undone and redone at will using the Undo and Redo toolbar buttons or
+ the corresponding entries in the Edit menu.
+ There is no limit to the depth of the undo/redo stack. It is cleared only
+ when you quit the application or open a new journal.
+
+A journal is composed of one or more pages, whose characteristics can be
+modified independently of each other. Each page consists of a background
+and one or more layers stacked on top of the background. All drawing
+operations take place within a single layer, and do not affect the background
+or the other layers. You can think of the layers as transparent overlays:
+drawing and erasing always takes place on the topmost visible overlay.
+
+Layers are a convenient mechanism to add temporary annotations on top of a
+journal page: because of the logical separation between layers, erasing
+in the top layer will not affect the contents of the other layers, and
+the top layer can be easily discarded.
+
+The user interface either displays all pages in the journal below each other +("continuous mode") or a single page ("one-page mode"). You can switch +between the two modes by using the "Continuous" and "One page" entries in +the View menu. The default is the +continuous mode, best adapted to note-taking on multiple pages. The one-page +mode is more appropriate if your journal is a scrapbook in which the pages +have different characteristics (in particular, if you are annotating a +series of pictures of different sizes). +
++You can navigate the journal pages in several different ways: +
+Note: jumping to a page automatically selects the top-most layer in +that page. +
++To navigate the layers of a page, either use the layer selection box at +the bottom of the Xournal window, or use the "Show Layer" and "Hide Layer" +entries in the View menu. The basic rule to remember is that the display +shows all the layers underneath the currently select one, and while those +above it are hidden. +
++Note: the background layer cannot be drawn on; any attempt to draw on the +background will generate an error message and switch back to the first +layer. +
++Pages can be added to the journal by using the "New Page ..." entries in +the Journal menu. The newly created page has the same format and background as the +current page (for the "New Page Before" and "New Page After" commands), or +as the last page of the journal (for "New Page At End"). Additionally, +jumping to the next page when already on the last page creates a new page +at the end of the journal. +
++The "Delete Page" entry in the Journal menu removes the current page from +the journal. (Remember that you can always undo this operation if you +deleted a page by accident). +
++The "New Layer" entry in the Journal menu creates a new layer immediately +above the current one, while "Delete Layer" removes the current layer and +its contents (if you attempt to delete the only layer of a page, a new +empty layer will be automatically created). +
++The size of the current page can be modified using the "Paper Size" entry +in the Journal menu. Standard and custom sizes are available. +
++The background is either one of several kinds of standard paper types, or a +bitmap image, or a page of a PDF file. +
++To select a standard paper type as background for the current page, use +the "Paper Style" submenu of the Journal menu. The paper color can also +be changed using the "Paper Color" submenu of the Journal menu. +
++To use a PDF file as the background for a journal, see the paragraph +on PDF annotation below. +
++To load a bitmap image file for use as background for the current page, use +the "Load Background" entry of the Journal menu. This automatically +resizes the current page according to the size of the bitmap image, and +resets the zoom level to 100%. If ghostscript is installed on your +system, you can also use this method to import a fixed-resolution bitmap +version of a Postscript or PDF file; in that case, all pages will be +imported sequentially as backgrounds into consecutive pages (this is not the +recommended method; PDF annotation is better in many respects). +
++To capture a screenshot of a window or the entire screen and make it +the background of the current page, use the "Background Screenshot" entry of +the Journal menu. This will iconify the Xournal window; click in any window +(after ensuring it is fully visible) to capture its contents, or click on +the desktop (or screen background) to capture the entire screen. +
+Important note: by default, bitmap images loaded using the "Load
+Background" command will not be saved with the journal; instead, the journal
+file will contain a reference to the absolute location of the image file.
+This means that the background will become unavailable if the image file
+is moved or deleted. To avoid this, check the option "Attach file to the
+journal" at the bottom of the file selection dialog box.
+This option only applies to bitmap image files loaded from disk;
+screenshot backgrounds (and bitmaps converted from PS/PDF files using
+ghostscript) are automatically "attached" to the journal file: when the
+journal is saved, they will be saved (in PNG format) along with it
+(using file names of the form *.xoj.bg_*.png).
+
+Rescaling and anti-aliasing: by default,
+bitmap backgrounds are rescaled and anti-aliased as needed when the zoom
+level is changed, to ensure their appearance always remains acceptable.
+Because this consumes a lot of memory and CPU resources, by default this
+rescaling is performed on-demand as each page becomes visible. This means
+that you will occasionally notice bitmap backgrounds being smoothed while
+you are scrolling inside the document (at large zoom levels, this can slow
+down the screen refresh rate noticeably). If you'd prefer all backgrounds to
+be rescaled immediately upon changing the zoom level (slower but maybe more
+intuitive), disable the "Progressive Backgrounds" option in the Options
+menu.
+If you are handling large bitmaps, you can save memory and CPU resources (at the
+expense of quality) by disabling the "Antialiased Bitmaps" option in the Options menu.
+
+Xournal can be used to annotate PDF files, by loading the pages of a PDF +file as backgrounds for a journal. This feature requires the +pdftoppm converter to be installed (this is part of the xpdf + PDF file viewer). +
++The "Annotate PDF" command in the File menu can be used to load a PDF file +into a new (empty) journal. The page backgrounds and page sizes correspond +to the contents of the PDF file. (Most unencrypted PDF files should be +supported). +
++By default, the PDF file used to generate the backgrounds +will not be saved with the journal; instead, the journal +file will contain a reference to the absolute location of this file. +This means that all backgrounds will become unavailable if the PDF file +is moved or deleted (although Xournal will let you specify +the updated location of the PDF file when opening the journal +file). To avoid this, check the option "Attach file to the journal" +at the bottom of the dialog box when opening the PDF file. The PDF file will +then be saved along with the journal (using a file name of the form +*.xoj.bg.pdf). +
+Upon zooming, the page backgrounds are asynchronously updated +to fit the current display resolution. Since this process is quite slow and +memory-intensive, the pages are normally updated only as needed, when they +become visible on the screen (unless you disable the "Progressive +Backgrounds" option in the Options menu). This means that you will +occasionally notice the page backgrounds being updated while you are +scrolling inside the document (at large zoom levels, it can take a while +for the updated background to appear). However, since the backgrounds are +generated asynchronously by a separate Unix process, you can keep drawing in the journal +while the update process is still in progress. +
++It is strongly recommended that you do not resize PDF pages (using the +"Paper Size" command). This will result in extremely ugly rendering, as +the PDF converter is unable to render bitmaps with +non-standard aspect ratios. +
++While you can perform all sorts of page operations on a journal file +that was created from a PDF file (such as duplicating or deleting pages, +inserting pages with blank or bitmapped backgrounds, ...), it is not +possible to include pages from more than one PDF file into a single journal +document. If you need to annotate two or more PDF files inside a same +journal document, please consider using an external utility for merging +PDF files (for example pdfmerge). +
+Xournal uses the gnome-print architecture for printing. While it is very +powerful, some aspects of the API leave to be desired, +and future versions of Xournal will probably also include a native +Postscript/PDF printing feature. +
++The "Printer" tab of the print dialog box lets you select a printer +(either one of the printers installed on your system, or the generic +Postscript printer, or the PDF virtual printer). The "Job" tab lets you +select a range of pages to print (the default is to print the entire +journal). The "Paper" tab lets you select the paper size. Each page +of the journal is automatically rescaled so as to fit the paper size. +(minus a 5% margin all around). +
++The settings are currently not saved properly from one print job to +the next, so make sure to select the appropriate printer and verify +the paper size. When printing to a file (Postscript or PDF), Xournal +attempts to pre-fill the output file name (for the Postscript driver +this often fails due to gnome-print API issues). +
++The "Print to PDF" entry of the File menu directly generates a PDF file +using the PDF virtual printer, without bringing up the dialog box +(the page size is the default one for that printer, usually A4). +Note that the PDF virtual printer produces files that are very large +and far from optimal, so in the current state of things it is better +to generate a Postscript file and use a converter such as ps2pdf. +
++The gnome-print architecture also forces page backgrounds (bitmaps +and PDF) to be generated as uncompressed bitmaps, which leads to gigantic +print job files. An alternative to gnome-print will be +implemented in a future release of Xournal. +
+Xournal is written by Denis Auroux
+(auroux@math.mit.edu).
+
It is distributed under the GNU General Public License.
+
Feel free to contact me with bug reports and suggestions; I apologize +in advance if I am unable to respond properly to some requests. +List of known bugs/misfeatures (no need to report them again): +
+Version 0.2 (January 29, 2006): +
+Version 0.1.1 (January 5, 2006): +
+Version 0.1 (January 2, 2006): initial release. +
++Features yet to be implemented: +
+XOJ files are gzipped XML-like files. A more precise documentation of +the file format will be added at a later date. Meanwhile, most of the +format should be easy to figure out by trial-and-error or by looking +at the source; if some details are unclear, feel free to ask. +
++The following libraries are required to run Xournal (they are standard on +modern Linux distributions such as Fedora Core 3 or later, or RHEL 4 or +later): +
+ Additionally: +
+To compile Xournal, you also need the development packages for the above +libraries (packages gtk2-devel, libgnomecanvas-devel, libgnomeprint22-devel, +libgnomeprintui22-devel, and dependencies), as well as autoconf and +automake. +
++Download the Xournal distribution tar.gz file, and any needed dependencies. +
+
+Binary installation in /usr/local:
+Run (as root) the installer script
+
./install-binary(and upgrade GTK+ and the other libraries if needed). + +
+Binary installation in home directory:
+Run (as any user) the installer script
+
./install-binary(and hope that the required libraries are +installed on your system). + +
+Compilation and installation in /usr/local: +
+./autogen.sh +make +(as root) make install ++ +
+Compilation and installation in $HOME: +
+./autogen.sh +./configure --prefix=$HOME +make +make install ++ +
Configure error message:
+If autogen.sh generates the error message
+
+configure: error: Library requirements (gtk+-2.0 >= 2.4.0 libgnomecanvas-2.0 >= 2.4.0 libgnomeprintui-2.2 >= 2.0.0) not met
+
+even though you have sufficiently recent versions of these libraries on your
+system, then you need to install some missing development packages.
+
+Configuring the tablet devices properly is unfortunately not as simple as it +ought to be. This is a subject worthy of a detailed how-to document; +meanwhile, here are some hints about how to configure your tablet. +
++Xournal uses the XInput extension to obtain high-resolution coordinates for +strokes drawn using the stylus. If you decide that getting just the right +XInput configuration isn't worth the effort, you can disable XInput features +by unsetting the "Use XInput" option in the Options menu. The price to pay +is a lower graphics quality, as the resolution of all strokes then drops to +1 pixel (instead of the native resolution of the tablet device, which can +be higher by several orders of magnitude). +
++The configuration of tablet devices is controlled in the X server's +configuration file (usually XF86Config or xorg.conf depending on your +distribution). The ServerLayout section should contain lines like: +
+Section "ServerLayout" + ... + InputDevice "cursor" "SendCoreEvents" + InputDevice "stylus" "SendCoreEvents" + InputDevice "eraser" "SendCoreEvents" +EndSection ++(the last one only if your stylus has an eraser tip), and your configuration +file should include sections such as +
+Section "InputDevice" + Identifier "cursor" + Driver "wacom" + Option "Device" "/dev/ttyS0" + Option "Type" "cursor" + Option "ForceDevice" "ISDV4" + Option "BottomX" "28800" + Option "BottomY" "21760" + Option "Mode" "absolute" +EndSection + +Section "InputDevice" + Identifier "stylus" + Driver "wacom" + Option "Device" "/dev/ttyS0" + Option "Type" "stylus" + Option "ForceDevice" "ISDV4" + Option "BottomX" "28800" + Option "BottomY" "21760" + Option "Mode" "absolute" +EndSection + +Section "InputDevice" + Identifier "eraser" + Driver "wacom" + Option "Device" "/dev/ttyS0" + Option "Type" "eraser" + Option "ForceDevice" "ISDV4" + Option "BottomX" "28800" + Option "BottomY" "21760" + Option "Mode" "absolute" +EndSection ++The actual settings will depend on your hardware; look on the web for Linux +installation instructions specific to your model: for example, the +"Device" settings above correspond to a serial port protocol, many tablets +use USB instead; the BottomX and BottomY values correspond to the physical +resolution of the tablet and will vary from one model to another. + +
+If the mouse pointer does not follow accurately the position of the stylus, +this is an indication that your tablet is not properly calibrated. If you +have the linuxwacom package, you can try modifying the tablet calibration +using xsetwacom. The relevant parameters are named TopX, BottomX, +TopY, BottomY, and need to be set separately for the stylus and for the +eraser. For example: +
+ xsetwacom set stylus TopX 270 + xsetwacom set stylus BottomX 28510 + ... ++(the TopX and TopY parameters default to 0 if you haven't set them in your +X server's configuration file). Experiment with these parameters until you +find the right calibration settings for your tablet (i.e., the mouse pointer +appears right under the tip of the stylus). + +
+Once you have found the perfect settings for your tablet, update your X +server's configuration file (due to issues with some versions of the +linuxwacom driver, the tablet calibration information is often not updated +properly when using xsetwacom). +
++Important: due to issues with the linuxwacom driver, it is important +to either upgrade your driver to a patched +version, or restrict your choice of settings as follows: +
+This is due to misfeatures in the linuxwacom driver. Typically, this +will happen in all of the following cases: +
+I have also had a report that one of the workarounds used by Xournal to +bypass a calibration bug in GTK+ can actually entirely prevent strokes +from being drawn. If you are being unsuccessful at drawing in Xournal +with XInput enabled, try recompiling after changing the first line of +src/main.c to +
#define ENABLE_XINPUT_BUGFIX 0+If this modification does improve things for you, and if you have a bit +of spare time to help investigate the causes of this problem, please +contact me. + +
+You need an X server that supports the RANDR extension, and a +patched version of the linuxwacom +driver to support on-the-fly rotation. +
++To set the tablet in portrait mode: +
+ xrandr -o 3 + xsetwacom set stylus Rotate cw ++To return to landscape mode: +
+ xrandr -o 0 + xsetwacom set stylus Rotate none ++Note: you should not rotate the display while Xournal is running, +otherwise the tablet calibration in Xournal may (and most likely will) +become incorrect. +Exit Xournal and restart it after the display has been rotated. + + +
+This patch fixes rotation and calibration issues with the linuxwacom driver +version 0.7.0. +