From ece65f3e9d935ad4ca0b6f9d626288908c2ad59e Mon Sep 17 00:00:00 2001 From: auroux Date: Mon, 30 Jan 2006 03:02:59 +0000 Subject: [PATCH] Initial revision --- html-doc/manual.html | 735 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 735 insertions(+) create mode 100644 html-doc/manual.html diff --git a/html-doc/manual.html b/html-doc/manual.html new file mode 100644 index 0000000..44681d3 --- /dev/null +++ b/html-doc/manual.html @@ -0,0 +1,735 @@ + + + +Xournal User's manual + + + +

+ Xournal User's Manual +

+

+ 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). +

+

Table of contents

+

+

+

+
+ +

Getting started

+

+ 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 drawing and selection tools

+

The pen

+

+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

+

+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): +

+

+

The highlighter

+

+ 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

+

+ 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. +

+

Default tools

+

+ 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. +

+ +

+ Thickness buttons

+

+ 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. +

+

Rectangle selection

+

+ 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. +

+

Vertical space

+

+ 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). +

+

Undo and redo

+

+ 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. +

+ +

Pages, layers, and backgrounds

+

+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. +

+

Navigating the journal

+

+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: +

+As a convenient shortcut, going forward one page (or pressing the + button +in the selection box) when already at the end of the journal creates a new +page at the end of the journal. +

+

+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. +

+

Managing pages and layers

+

+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). +

+

Paper formats and backgrounds

+

+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. +

+ + +

PDF annotation

+

+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). +

+ +

Printing

+

+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. +

+ +

Author information, license, bug-reports

+

+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): +

+If you find a sequence of operations which crashes Xournal in a reproducible +manner, please send detailed instructions on how to reproduce the crash. +A core file may also be helpful. +

+
+ +

Version history

+

+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: +

+

+
+ +

The file format

+

+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. +

+
+ +

Installation issues

+

Dependencies

+

+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. +

+

Compilation and installation procedure

+

+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. +

+
+ +

Tablet calibration issues

+

+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. +

+

Basics

+

+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. +

+

The cursor doesn't appear in the right place...

+

+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: +

+

+

Strokes aren't drawn under the cursor...

+

+This is due to misfeatures in the linuxwacom driver. Typically, this +will happen in all of the following cases: +

+Future versions of the driver may fix these issues. Meanwhile, you can +either disable XInput support in Xournal (in the Options menu), at a +price of a severe loss of resolution (and the eraser tip won't be detected +anymore), or apply this patch +to the wacom driver. +

+

+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. +

+

On-the-fly display rotation

+

+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. +

+ +

Linuxwacom patch for calibration and rotation

+

+This patch fixes rotation and calibration issues with the linuxwacom driver +version 0.7.0. +

+

+ + -- 2.39.2