html-doc/manual.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head><title>Xournal User's manual</title></head>
   5 <style>
   6  .subtitle {
   7   font-family: Helvetica, Arial, sans-serif;
   8   font-weight: bold;
   9   font-size: 1.3em;
  10   color: rgb(0,150,0);
  11  }
  12  .subsub {
  13   font-family: Helvetica, Arial, sans-serif;
  14   font-weight: bold;
  15   font-size: 1em;
  16   color: rgb(0,150,0);
  17  }
  18  a { color: rgb(0,0,255); text-decoration: none; }
  19  a:hover { text-decoration: underline; }
  20 </style>
  21 <body bgcolor="#ffffff" style="background: rgb(255,255,255)">
  22
  23 <h2 class="subtitle" style="text-align: center; color: rgb(0,0,200)">
  24   Xournal User's Manual
  25 </h2>
  26 <p style="font-size: 0.95em; text-align: center; color: rgb(0,0,0)">
  27  Version 0.3
  28 </p>
  29 <hr />
  30 <p>
  31  Xournal is an application for notetaking, sketching, keeping
  32  a journal using a stylus. It is free software (GNU GPL) and runs
  33  on Linux (recent distributions) and other GTK+/Gnome platforms.
  34  It is similar to Microsoft Windows Journal or
  35  to other alternatives such as
  36  <a href="http://www.dklevine.com/general/software/tc1000/jarnal.htm">Jarnal</a>
  37  and <a href="http://www.adebenham.com/gournal/">Gournal</a>.
  38 </p>
  39 <p>
  40 Xournal can be downloaded at
  41 <a href="http://math.mit.edu/~auroux/software/xournal/">http://math.mit.edu/~auroux/software/xournal/</a>
  42 </p>
  43 <p>
  44  Xournal aims to provide superior graphical quality (subpixel resolution) and overall
  45  functionality; however it lacks the collaborative features of Jarnal.
  46  Since Xournal is still in its early development stages, it may not
  47  be fully stable, and some features have not been implemented yet.
  48 </p>
  49 <h2 class="subtitle">Table of contents</h2>
  50 <p>
  51  <ul>
  52   <li> <a href="manual.html#getting-started">Getting started</a> </li>
  53   <li> <a href="manual.html#tools">The drawing and selection tools</a> </li>
  54   <li> <a href="manual.html#pages-layers">Pages, layers, and backgrounds</a> </li>
  55   <li> <a href="manual.html#printing">Printing</a> </li>
  56   <li> <a href="manual.html#author">Author information, license, bug-reports</a> </li>
  57   <li> <a href="manual.html#changelog">Version history</a> </li>
  58   <li> <a href="manual.html#file-format">The file format</a> </li>
  59   <li> <a href="manual.html#installation">Installation issues</a> and
  60        <a href="manual.html#calibration">tablet calibration issues</a> </li>
  61  </ul>
  62 </p>
  63 <hr />
  64 <a name="getting-started"></a>
  65 <h2 class="subtitle">Getting started</h2>
  66 <p>
  67  Xournal's user interface is (hopefully) intuitive, and if you don't run
  68  into <a href="manual.html#installation">installation</a> or
  69  <a href="manual.html#calibration">tablet calibration</a> issues, you'll
  70  probably be able to start taking notes without referring to this manual.
  71  <br />
  72  Here is a screenshot of the user interface (click to enlarge):
  73 </p>
  74 <p style="text-align: center">
  75  <a href="screenshot.png">
  76    <img src="screenshot.png" style="width: 321px; height: 176px" />
  77  </a>
  78 </p>
  79 <p>
  80 Refer the next few sections of this manual for more information about
  81 the various functionalities.
  82 </p>
  83 <hr />
  84 <a name="tools"></a>
  85 <h2 class="subtitle">The drawing and selection tools</h2>
  86 <h3 class="subsub"><img src="pixmaps/pencil.png"> The pen</h3>
  87 <p>
  88 The pen is the default drawing tool in Xournal. It comes in a variety
  89 of colors (see the color toolbar buttons and the Color submenu of the
  90 Tools menu) and thicknesses (see the
  91 <a href="manual.html#thicknesses">thickness</a> toolbar buttons and
  92 the Pen Options submenu of the Tools menu).
  93 </p>
  94 <h3 class="subsub"><img src="pixmaps/eraser.png"> The eraser</h3>
  95 <p>
  96 The eraser lets you erase what you have drawn.
  97 By default, stylus buttons 2 and 3 (mouse middle or right buttons) are
  98 mapped to the eraser tool.
  99 <br />
 100 The eraser comes in three different thicknesses (selected using the
 101 <a href="manual.html#thicknesses">thickness</a> toolbar buttons),
 102 and can operate in three different modes (Eraser Options submenu of
 103 the Tools menu):
 104 <ul>
 105  <li>
 106    Standard mode (default): the eraser deletes portions
 107    of strokes previously drawn using the pen or the highlighter.
 108    In this mode, if you erase in the middle of a stroke, the remaining
 109    portions of the stroke are automatically split into shorter strokes.
 110    The background of the page (and the lower layers) are not erased.
 111  </li>
 112  <li>
 113    Whiteout: the eraser is actually a thick white pen, and simply covers
 114    whatever lies underneath, including the background of the page.
 115  </li>
 116  <li>
 117    Delete strokes: whenever the eraser comes in contact with a previously
 118    drawn stroke, the entire stroke is deleted.
 119   </li>
 120 </ul>
 121 </p>
 122 <h3 class="subsub"><img src="pixmaps/highlighter.png"> The highlighter</h3>
 123 <p>
 124   Like the pen, the highlighter comes in a variety of colors (the default
 125   is yellow) and thicknesses. Use the color and thickness toolbar buttons
 126   to change these settings.
 127 </p>
 128 <h3 class="subsub"><img src="pixmaps/ruler.png"> The ruler</h3>
 129 <p>
 130   The ruler is not a tool by itself, but rather a special operating mode
 131   of the pen and highlighter tools. When it is enabled, these tools paint
 132   line segments instead of curvy strokes. For simplicity, selecting the
 133   ruler when not in pen or highlighter mode automatically selects the pen.
 134 </p>
 135 <h3 class="subsub"><img src="pixmaps/recycled.png"> Default tools</h3>
 136 <p>
 137   Each drawing tool (pen, eraser, highlighter) has a default setting
 138   (color, thickness, ...) associated to it.
 139   The "Default Pen", "Default Eraser", and "Default Highlighter" entries of
 140   the Tools menu select the appropriate tool and reset its settings to
 141   the defaults. The toolbar also includes a "Default" button which
 142   resets the currently selected drawing tool to its default settings,
 143   and a "Default Pen" button. <br />
 144   The "Set As Default" entry of the Tools menu takes the current settings
 145   of the currently selected drawing tool and makes them the new default.
 146 </p>
 147 <a name="thicknesses"></a>
 148 <h3 class="subsub"><img src="pixmaps/thin.png"> <img src="pixmaps/medium.png">
 149   <img src="pixmaps/thick.png"> Thickness buttons</h3>
 150 <p>
 151   These three buttons control the thickness of the current drawing tool
 152   (pen, eraser, or highlighter). The thickness can also be adjusted using
 153   the appropriate sub-menu of the Tools menu.
 154 </p>
 155 <h3 class="subsub"><img src="pixmaps/rect-select.png"> Rectangle selection</h3>
 156 <p>
 157   This tool lets you select a rectangular region of the current layer.
 158   All the strokes which are entirely contained within the rectangular region
 159   are selected.
 160   The selection can be moved within its page by clicking inside the
 161   selection rectangle and dragging the cursor. If the cursor is dragged
 162   to a different page, the selection will be moved to the topmost layer of
 163   that page.
 164 </p>
 165 <p>
 166   The selection can be cut, duplicated, etc. (including to a different page
 167   or to a different journal) using the copy-paste toolbar buttons or the
 168   corresponding entries of the Edit menu.
 169 </p>
 170 <h3 class="subsub"><img src="pixmaps/stretch.png"> Vertical space</h3>
 171 <p>
 172   This tool lets you insert or remove vertical space within the page:
 173   all the items of the current layer which lie entirely between the cursor
 174   position and the end of the page are moved up or down.
 175 </p>
 176 <p>
 177   Note that the background, and items on other layers, are not affected.
 178   Also, if you insert too much vertical space, some items may fall below
 179   the bottom of the page and become invisible. These items are not lost:
 180   to retrieve them, either use
 181   the vertical space tool again to remove the excess vertical
 182   space, or change the page height to an appropriate value (using the
 183   "Paper Size" entry in the Journal menu).
 184 </p>
 185 <p>
 186   If you drag the cursor below the bottom of the page (so that the
 187   entire block being moved has become invisible), the items will be moved
 188   to the next page (topmost layer); however, any items that were already
 189   present on the next page are left unchanged. Similarly, dragging the
 190   cursor above the top of the page so that the entire block being moved
 191   becomes invisible results in the items being moved to the previous page.
 192 </p>
 193 <h3 class="subsub">Undo and redo</h3>
 194 <p>
 195   All operations performed on the currently open journal (drawing, erasing,
 196   cut-and-paste; adding, deleting, and reformatting pages; etc.) can be
 197   undone and redone at will using the Undo and Redo toolbar buttons or
 198   the corresponding entries in the Edit menu.<br />
 199   There is no limit to the depth of the undo/redo stack. It is cleared only
 200   when you quit the application or open a new journal.
 201 </p>
 202 <a name="mappings"></a>
 203 <h3 class="subsub">Button mappings</h3>
 204 <p>
 205   Stylus buttons 2 and 3 (mouse middle and right buttons) can be mapped
 206   to different tools using the appropriate submenus in the Options menu
 207   (whereas the Tools menu and the toolbar buttons affect the primary tool
 208   assigned to button 1). The default mapping is the eraser.
 209 </p>
 210 <p><b>Advanced configuration:</b>
 211   if a secondary button is mapped to a drawing tool (pen, eraser, or
 212   highlighter), the default is to "dynamically link" its settings to those
 213   of the primary tool, which means that each drawing tool has common
 214   settings (color, thickness, etc.) for all buttons.
 215   Dynamic linking of brush settings
 216   can be disabled by selecting the "Copy of current brush" option in the
 217   "Button mapping" submenu. The settings of the tool for button 2 or 3 are
 218   copied from the button 1 settings at the time when you select the option,
 219   and afterwards they are no longer updated when the button 1 settings are
 220   modified, thus making it possible to assign pens of different colors or
 221   thicknesses to different buttons.
 222 </p>
 223 <p>
 224   Another option that affects button mappings is the "Eraser tip" option.
 225   If this option is turned on and the XInput extensions are enabled, then
 226   the eraser tip of your tablet's stylus will automatically be remapped to
 227   the eraser tool. This behavior, which overrides all other button mappings,
 228   is most useful if your X server is configured to map the eraser tip of
 229   your tablet's stylus to button 1.
 230 </p>
 231 <hr />
 232 <a name="pages-layers"></a>
 233 <h2 class="subtitle">Pages, layers, and backgrounds</h2>
 234 <p>
 235 A journal is composed of one or more pages, whose characteristics can be
 236 modified independently of each other. Each page consists of a background
 237 and one or more layers stacked on top of the background. All drawing
 238 operations take place within a single layer, and do not affect the background
 239 or the other layers. You can think of the layers as transparent overlays:
 240 drawing and erasing always takes place on the topmost visible overlay.
 241 <br />
 242 Layers are a convenient mechanism to add temporary annotations on top of a
 243 journal page: because of the logical separation between layers, erasing
 244 in the top layer will not affect the contents of the other layers, and
 245 the top layer can be easily discarded.
 246 </p>
 247 <h3 class="subsub">Navigating the journal</h3>
 248 <p>
 249 The user interface either displays all pages in the journal below each other
 250 ("continuous mode") or a single page ("one-page mode"). You can switch
 251 between the two modes by using the "Continuous" and "One page" entries in
 252 the View menu. The default is the
 253 continuous mode, best adapted to note-taking on multiple pages. The one-page
 254 mode is more appropriate if your journal is a scrapbook in which the pages
 255 have different characteristics (in particular, if you are annotating a
 256 series of pictures of different sizes).
 257 </p>
 258 <p>
 259 You can navigate the journal pages in several different ways:
 260 <ul>
 261  <li> using the navigation toolbar buttons (or the corresponding entries
 262   in the View menu) to go back or forward one page, or to jump to the first
 263   or last page of the journal;
 264  </li>
 265  <li> in continuous mode, scrolling down to the desired page;
 266  </li>
 267  <li> entering a value or using the +/- buttons in the page selection box
 268   at the lower-left corner of the Xournal window.
 269  </li>
 270 </ul>
 271 As a convenient shortcut, going forward one page (or pressing the + button
 272 in the selection box) when already at the end of the journal creates a new
 273 page at the end of the journal.
 274 </p>
 275 <p>
 276 Note: jumping to a page automatically selects the top-most layer in
 277 that page.
 278 </p>
 279 <p>
 280 To navigate the layers of a page, either use the layer selection box at
 281 the bottom of the Xournal window, or use the "Show Layer" and "Hide Layer"
 282 entries in the View menu. The basic rule to remember is that the display
 283 shows all the layers underneath the currently select one, and while those
 284 above it are hidden.
 285 </p>
 286 <p>
 287 Note: the background layer cannot be drawn on; any attempt to draw on the
 288 background will generate an error message and switch back to the first
 289 layer.
 290 </p>
 291 <h3 class="subsub">Managing pages and layers</h3>
 292 <p>
 293 Pages can be added to the journal by using the "New Page ..." entries in
 294 the Journal menu. The newly created page has the same format and background as the
 295 current page (for the "New Page Before" and "New Page After" commands), or
 296 as the last page of the journal (for "New Page At End"). Additionally,
 297 jumping to the next page when already on the last page creates a new page
 298 at the end of the journal.
 299 </p>
 300 <p>
 301 The "Delete Page" entry in the Journal menu removes the current page from
 302 the journal. (Remember that you can always undo this operation if you
 303 deleted a page by accident).
 304 </p>
 305 <p>
 306 The "New Layer" entry in the Journal menu creates a new layer immediately
 307 above the current one, while "Delete Layer" removes the current layer and
 308 its contents (if you attempt to delete the only layer of a page, a new
 309 empty layer will be automatically created).
 310 </p>
 311 <h3 class="subsub">Paper formats and backgrounds</h3>
 312 <p>
 313 The size of the current page can be modified using the "Paper Size" entry
 314 in the Journal menu. Standard and custom sizes are available.
 315 </p>
 316 <p>
 317 The background is either one of several kinds of standard paper types, or a
 318 bitmap image, or a page of a PDF file.
 319 </p>
 320 <p>
 321 To select a <b>standard paper type</b> as background for the current page, use
 322 the "Paper Style" submenu of the Journal menu. The paper color can also
 323 be changed using the "Paper Color" submenu of the Journal menu.
 324 </p>
 325 <p>
 326 To use a <b>PDF file</b> as the background for a journal, see the paragraph
 327 on <a href="manual.html#pdfannotate">PDF annotation</a> below.
 328 </p>
 329 <p>
 330 To load a <b>bitmap image file</b> for use as background for the current page, use
 331 the "Load Background" entry of the Journal menu. This automatically
 332 resizes the current page according to the size of the bitmap image, and
 333 resets the zoom level to 100%. If <i>ghostscript</i> is installed on your
 334 system, you can also use this method to import a fixed-resolution bitmap
 335 version of a Postscript or PDF file; in that case, all pages will be
 336 imported sequentially as backgrounds into consecutive pages (this is not the
 337 recommended method; PDF annotation is better in many respects).
 338 </p>
 339 <p>
 340 To capture a <b>screenshot</b> of a window or the entire screen and make it
 341 the background of the current page, use the "Background Screenshot" entry of
 342 the Journal menu. This will iconify the Xournal window; click in any window
 343 (after ensuring it is fully visible) to capture its contents, or click on
 344 the desktop (or screen background) to capture the entire screen.
 345 </p>
 346 <p><b>Important note:</b> by default, bitmap images loaded using the "Load
 347 Background" command will not be saved with the journal; instead, the journal
 348 file will contain a reference to the absolute location of the image file.
 349 This means that the background will become unavailable if the image file
 350 is moved or deleted. To avoid this, check the option "Attach file to the
 351 journal" at the bottom of the file selection dialog box.<br />
 352 This option only applies to bitmap image files loaded from disk;
 353 screenshot backgrounds (and bitmaps converted from PS/PDF files using
 354 ghostscript) are automatically "attached" to the journal file: when the
 355 journal is saved, they will be saved (in PNG format) along with it
 356 (using file names of the form *.xoj.bg_*.png).
 357 </p>
 358 <p>
 359 <b>Rescaling and anti-aliasing:</b> by default,
 360 bitmap backgrounds are rescaled and anti-aliased as needed when the zoom
 361 level is changed, to ensure their appearance always remains acceptable.
 362 Because this consumes a lot of memory and CPU resources, by default this
 363 rescaling is performed on-demand as each page becomes visible. This means
 364 that you will occasionally notice bitmap backgrounds being smoothed while
 365 you are scrolling inside the document (at large zoom levels, this can slow
 366 down the screen refresh rate noticeably). If you'd prefer all backgrounds to
 367 be rescaled immediately upon changing the zoom level (slower but maybe more
 368 intuitive), disable the "Progressive Backgrounds" option in the Options
 369 menu.<br />
 370 If you are handling large bitmaps, you can save memory and CPU resources (at the
 371 expense of quality) by disabling the "Antialiased Bitmaps" option in the Options menu.
 372 </p>
 373
 374 <a name="pdfannotate"></a>
 375 <h3 class="subsub">PDF annotation</h3>
 376 <p>
 377 Xournal can be used to annotate PDF files, by loading the pages of a PDF
 378 file as backgrounds for a journal. This feature requires the
 379 <i>pdftoppm</i> converter to be installed (this is part of the <i>xpdf</i>
 380 &nbsp;PDF file viewer).
 381 </p>
 382 <p>
 383 The "Annotate PDF" command in the File menu can be used to load a PDF file
 384 into a new (empty) journal. The page backgrounds and page sizes correspond
 385 to the contents of the PDF file. (Most unencrypted PDF files should be
 386 supported).
 387 </p>
 388 <p>
 389 By default, the PDF file used to generate the backgrounds
 390 will not be saved with the journal; instead, the journal
 391 file will contain a reference to the absolute location of this file.
 392 This means that all backgrounds will become unavailable if the PDF file
 393 is moved or deleted (although Xournal will let you specify
 394 the updated location of the PDF file when opening the journal
 395 file). To avoid this, check the option "Attach file to the journal"
 396 at the bottom of the dialog box when opening the PDF file. The PDF file will
 397 then be saved along with the journal (using a file name of the form
 398 *.xoj.bg.pdf).
 399 <p>
 400 Upon zooming, the page backgrounds are asynchronously updated
 401 to fit the current display resolution. Since this process is quite slow and
 402 memory-intensive, the pages are normally updated only as needed, when they
 403 become visible on the screen (unless you disable the "Progressive
 404 Backgrounds" option in the Options menu). This means that you will
 405 occasionally notice the page backgrounds being updated while you are
 406 scrolling inside the document (at large zoom levels, it can take a while
 407 for the updated background to appear). However, since the backgrounds are
 408 generated asynchronously by a separate Unix process, you can keep drawing in the journal
 409 while the update process is still in progress.
 410 </p>
 411 <p>
 412 It is strongly recommended that you do not resize PDF pages (using the
 413 "Paper Size" command). This will result in extremely ugly rendering, as
 414 the PDF converter is unable to render bitmaps with
 415 non-standard aspect ratios.
 416 </p>
 417 <p>
 418 While you can perform all sorts of page operations on a journal file
 419 that was created from a PDF file (such as duplicating or deleting pages,
 420 inserting pages with blank or bitmapped backgrounds, ...), it is not
 421 possible to include pages from more than one PDF file into a single journal
 422 document. If you need to annotate two or more PDF files inside a same
 423 journal document, please consider using an external utility for merging
 424 PDF files (for example <i>pdfmerge</i>).
 425 <hr />
 426 <a name="printing"></a>
 427 <h2 class="subtitle">Printing</h2>
 428 <p>
 429 Xournal uses the gnome-print architecture for printing. While it is very
 430 powerful, some aspects of the API leave to be desired. As of version 0.3,
 431 Xournal also includes a native PDF printing feature.
 432 </p>
 433 <h3 class="subsub">Printing via gnome-print</h3>
 434 <p>
 435 The "Printer" tab of the print dialog box lets you select a printer
 436 (either one of the printers installed on your system, or the generic
 437 Postscript printer, or the PDF virtual printer). The "Job" tab lets you
 438 select a range of pages to print (the default is to print the entire
 439 journal). The "Paper" tab lets you select the paper size. Each page
 440 of the journal is automatically rescaled so as to fit the paper size.
 441 (minus a 5% margin all around).
 442 </p>
 443 <p>
 444 The settings are currently not saved properly from one print job to
 445 the next, so make sure to select the appropriate printer and verify
 446 the paper size. When printing to a file (Postscript or PDF), Xournal
 447 attempts to pre-fill the output file name (for the Postscript driver
 448 this often fails due to gnome-print API issues).
 449 </p>
 450 <p>
 451 Note that the PDF virtual printer produces files that are very large
 452 and far from optimal, so its use is not recommended.
 453 The gnome-print architecture also forces page backgrounds (bitmaps
 454 and PDF) to be generated as uncompressed bitmaps, which leads to gigantic
 455 print job files. A better alternative is to export a PDF file, and
 456 print the PDF file.
 457 </p>
 458 <h3 class="subsub">Exporting to PDF</h3>
 459 <p>
 460 Starting with version 0.3, Xournal provides its own PDF rendering
 461 engine. The "Export to PDF" command (in the File menu) produces a
 462 PDF-1.4 file from the currently loaded document. The resulting PDF
 463 file is much more compact than those produced via gnome-print, and
 464 its pages have the same size as in Xournal. Highlighter strokes
 465 are rendered in a partially transparent manner (note however that
 466 applications such as xpdf and ghostview do not always handle
 467 PDF transparency properly).
 468 </p>
 469 <p>
 470 Xournal also includes a PDF file parser compatible with PDF format
 471 version 1.4; the compression features of PDF 1.5 (Acrobat 6) are
 472 not supported. When exporting a document that uses PDF
 473 backgrounds, Xournal attempts to preserve most of the structure of
 474 the original PDF file (however, auxiliary data such as thumbnails, hyperlinks,
 475 and annotations are lost). If Xournal is unable to parse the PDF
 476 file, the backgrounds are converted to (compressed) bitmaps and a new
 477 PDF file is generated from scratch.
 478 </p>
 479 <hr />
 480 <a name="author"></a>
 481 <h2 class="subtitle">Author information, license, bug-reports</h2>
 482 <p>
 483 Xournal is written by Denis Auroux
 484 (aur<!--despam-->oux<span>&#x40;</span><span>math</span>&#x2e;<span>mit&#x2e;edu).
 485 <br />It is distributed under the GNU General Public License.
 486 </p>
 487 <p>Feel free to contact me with bug reports and suggestions; I apologize
 488 in advance if I am unable to respond properly to some requests.
 489 </p><p>
 490 If you find a sequence of operations which crashes Xournal in a reproducible
 491 manner, please send detailed instructions on how to reproduce the crash.
 492 A core file may also be helpful.
 493 </p>
 494 <p>
 495 Bug reports and suggestions can also be submitted on Xournal's
 496 <a href="http://www.sourceforge.net/projects/xournal/">SourceForge page.</a>
 497 </p>
 498 <hr />
 499 <a name="changelog"></a>
 500 <h2 class="subtitle">Version history</h2>
 501 <p>
 502 Version 0.3 (July 23, 2006):
 503 <ul>
 504  <li>new PDF rendering engine: export to PDF generates optimized files
 505    (smaller and more accurate)</li>
 506  <li>export to PDF handles PDF backgrounds (up to PDF-1.4) natively
 507     (without conversion to bitmap)</li>
 508  <li>default thickness of erasers and highlighters slightly increased</li>
 509  <li>zoom dialog box with input box and "fit to page height" option</li>
 510  <li>file format documentation added to the user's manual</li>
 511 </ul>
 512 </p>
 513 <p>
 514 Version 0.2.2 (June 5, 2006):
 515 <ul>
 516  <li>mapping of tools to stylus buttons (the options menu has new entries
 517     to allow the mapping of buttons 2 and 3 to arbitrary tools; the tools
 518     menu and toolbar affect the settings for button 1)
 519     (see <a href="manual.html#mappings">here</a>)</li>
 520  <li>moving selection by drag-and-drop works across page boundaries</li>
 521  <li>vertical space tool can move items to next page (only when the entire
 522     block being moved has crossed the page boundary; items on the new page
 523     are not moved)</li>
 524  <li>"apply to all pages" is now a toggle button affecting the behavior of
 525     paper size, color, and style commands</li>
 526  <li>change in the behavior of the selection upon switching between tools</li>
 527 </ul>
 528 </p>
 529 <p>
 530 Version 0.2.1 (June 3, 2006):
 531 <ul>
 532  <li>recently used files listed in file menu</li>
 533  <li>can change color or thickness of pen strokes in selection</li>
 534  <li>function to apply paper style to all pages</li>
 535  <li>can specify on command line a PDF file to annotate</li>
 536  <li>suggest a derived file name for PDF annotation</li>
 537  <li>speed up switching between pages</li>
 538  <li>fixed a bug in XInput initialization (thanks to Luca de Cicco)</li>
 539  <li>fixed a bug in print ranges (thanks to Mathieu Bouchard)</li>
 540  <li>fixed a refresh bug in rescaling bitmap backgrounds</li>
 541 </ul>
 542 </p>
 543 <p>
 544 Version 0.2 (January 29, 2006):
 545 <ul>
 546  <li>PDF file annotation using xpdf's pdftoppm
 547       (PDF backgrounds updated asynchronously at all resolutions)</li>
 548  <li>PS/PDF backgrounds (as bitmaps at fixed resolution) using ghostscript</li>
 549  <li>option to antialias and filter bitmap backgrounds when zooming</li>
 550  <li>option to emulate eraser tip with right mouse button</li>
 551  <li>binary installer allows non-root installation without compiling</li>
 552  <li>full-screen mode (patch contributed by Luca De Cicco)</li>
 553 </ul>
 554 </p>
 555 <p>
 556 Version 0.1.1 (January 5, 2006):
 557 <ul>
 558  <li> two bugfixes </li>
 559  <li> backward compatibility with GTK+ 2.4 </li>
 560 </ul>
 561 </p>
 562 <p>
 563 Version 0.1 (January 2, 2006): initial release.
 564 </p>
 565 <p>
 566 Features yet to be implemented:
 567 <ul>
 568  <li>freeform selection tool</li>
 569  <li>preferences file; persistent printer settings</li>
 570  <li>various functionalities (flatten layers, ...)</li>
 571 </ul>
 572 </p>
 573 <hr />
 574 <a name="file-format"></a>
 575 <h2 class="subtitle">The file format</h2>
 576 <h3 class="subsub">Overall structure</h3>
 577 <p>
 578 Xournal stores its data in gzipped XML-like files. The gzipped data consists
 579 of a succession of XML tags describing the document. By convention, the
 580 first few lines contain a header in the following format:
 581 <pre>
 582 &lt;?xml version="1.0" standalone="no"?&gt;
 583 &lt;title&gt;Xournal document - see http://math.mit.edu/~auroux/software/xournal/&lt;/title&gt;
 584 &lt;xournal version="..."/&gt;
 585 </pre>
 586 The &lt;title&gt; and &lt;xournal&gt; tags may only appear within the file
 587 header (not within the pages of the document). The <i>version</i> attribute of
 588 the &lt;xournal&gt; tag indicates which version of Xournal was used to
 589 create the document; it is currently ignored, but may be used in a later
 590 release if the file format changes in an incompatible manner.
 591 </p>
 592 <p>
 593 The rest of the file is a sequence of pages, specified by a
 594 &lt;page&gt; tag, whose attributes <i>width</i> and <i>height</i> specify the
 595 physical size of the page in points (1/72 in). The width and height
 596 parameters are floating point values. The format of a page is therefore:
 597 <pre>
 598 &lt;page width="..." height="..."&gt;
 599 ... page contents ...
 600 &lt;/page&gt;
 601 </pre>
 602 </p>
 603 <h3 class="subsub">Page background</h3>
 604 <p>
 605 The first entry within a page describes the page background.
 606 It consists of a &lt;background&gt; tag followed by several mandatory
 607 XML attributes. The first attribute is always <i>type</i>, which
 608 can take three possible values: "solid" for a solid background, "pixmap"
 609 for a bitmap background, and "pdf" if the background is a page of a PDF
 610 document. The rest of the attributes depends on the type of background.
 611 <ul>
 612 <li><p> Solid background: <tt>&lt;background type="solid" color="..."
 613 style="..." /&gt;</tt> <br />The <i>color</i> attribute takes one of
 614 the standard values "white", "yellow", "pink", "orange", "blue", "green",
 615 or can specify a hexadecimal RGBA value in the format "#rrggbbaa". The
 616 <i>style</i> attribute takes one of the standard values "plain", "lined",
 617 "ruled", or "graph".</p>
 618 </li>
 619 <li><p> Bitmap background: <tt>&lt;background type="pixmap" domain="..."
 620 filename="..." /&gt;</tt> <br />
 621 The <i>domain</i> attribute takes one of the standard values "absolute",
 622 "attach", or "clone". A value of "absolute" indicates that the bitmap is
 623 found in the file specified by <i>filename</i>. The bitmap can be in any
 624 format recognized by the gdk-pixbuf library; this includes most of the
 625 common bitmap formats (JPEG, PNG, BMP, GIF, PCX, PNM, TIFF, ...).
 626 <br />A value
 627 of "attach" indicates that the bitmap is an attachment to the Xournal file.
 628 The bitmap is in PNG format, and resides in a file whose name is derived
 629 from that of the main Xournal file by appending to it a dot and the contents
 630 of the <i>filename</i> attribute. For example, if the Xournal file is in
 631 <tt>file.xoj</tt> and the <i>filename</i> attribute is <tt>"bg_1.png"</tt>
 632 then the bitmap file is <tt>file.xoj.bg_1.png</tt> (Xournal saves attached
 633 bitmaps sequentially in files ...bg_1.png, ...bg_2.png, etc.)
 634 <br />A value of "clone" indicates that the bitmap is identical to the
 635 background of a previous page of the journal; the <i>filename</i> attribute
 636 then specifies the page number, starting with 0 for the first page. For
 637 example, if a <i>filename</i> value of <tt>"1"</tt> indicates that the
 638 background bitmap is identical to that of the second page.
 639 </p>
 640 </li>
 641 <li><p> PDF background: <tt>&lt;background type="pdf" domain="..."
 642 filename="..." pageno="..." /&gt;</tt> or
 643 <tt>&lt;background type="pdf" pageno="..." /&gt;</tt>
 644 <br />The <i>domain</i> and <i>filename</i> attributes must be specified
 645 for the first page of the journal that uses a PDF background, and must
 646 be omitted subsequently for every other page that uses a PDF background.
 647 The <i>domain</i> attribute takes one of the standard values
 648 "absolute" and "attach"; the PDF document is to be found in the file
 649 specified by <i>filename</i> (if <i>domain</i> is "absolute"), or in the
 650 file whose name is obtained by appending a dot and the contents of the
 651 <i>filename</i> attribute to the name of the main Xournal file (if
 652 <i>domain</i> is "attach"). The <i>pageno</i> attribute specifies which
 653 page of the PDF file is used as background, starting with 1 for the first
 654 page of the PDF file.
 655 </p>
 656 </li>
 657 </ul>
 658 </p>
 659 <h3 class="subsub">Layers and strokes</h3>
 660 <p>
 661 After the line specifying the background, the remainder of a &lt;page&gt;
 662 section is occupied by one or more layer sections
 663 <pre>&lt;layer&gt; ... &lt;/layer&gt;</pre>
 664 describing the various strokes within a layer. Every page must
 665 contain at least one layer; a layer may be empty. The successive layers
 666 are listed in their stacking order, from bottom to top.
 667 </p>
 668 <p>
 669 A layer consist of a collection of items, listed in the order in which
 670 they should be drawn
 671 (from bottom-most to top-most).
 672 As of the current version, the only legal contents within a layer are
 673 strokes. The format of a stroke is:
 674 <pre>&lt;stroke tool="..." color="..." width="..."&gt;
 675 ... list of coordinates ...
 676 &lt;/stroke&gt;
 677 </pre>
 678 The <i>tool</i> attribute can take the values "pen", "highlighter", or
 679 "eraser" depending on the tool used to create the stroke (pen, highlighter,
 680 or whiteout eraser); a value of "highlighter" indicates that the stroke
 681 should be painted in a partially transparent manner (Xournal uses an alpha
 682 coefficient of 0.5).
 683 The <i>color</i> attribute can take one of the standard values "black",
 684 "blue", "red", "green", "gray", "lightblue", "lightgreen", "magenta",
 685 "orange", "yellow", "white", or can specify a hexadecimal RGBA value in
 686 the format "#rrggbbaa". The <i>width</i> attribute is a floating-point
 687 number and specifies the width of the stroke in points (1/72 in).
 688 </p>
 689 <p>
 690 The list of coordinates is simply a succession of floating-point values,
 691 separated by whitespace.
 692 The number of given values must be even; consecutive pairs of values give
 693 the <i>x</i> and <i>y</i> coordinates of each point along the stroke.
 694 These values are expressed in points (1/72 in). The coordinates (0,0)
 695 represent the top-left corner of the page: hence x is measured from the left
 696 of the page, and y is measured from the top of the page.
 697 </p>
 698 <p>
 699 Every stroke must contain at least two points (four floating point values).
 700 Moreover, two consecutive points on the stroke should be spaced no more
 701 than 5 units apart or so; longer line segments should be subdivided as
 702 appropriate (otherwise the eraser tool will not interact properly with the
 703 stroke). The default precision used by Xournal for the x,y coordinates is
 704 0.01 unit (1/7200 in).
 705 </p>
 706 <hr />
 707 <a name="installation"></a>
 708 <h2 class="subtitle">Installation issues</h2>
 709 <h3 class="subsub">Dependencies</h3>
 710 <p>
 711 The following libraries are required to run Xournal (they are standard on
 712 modern Linux distributions such as Fedora Core 3 or later, or RHEL 4 or
 713 later):
 714 <ul>
 715  <li> the <b>gtk+</b> libraries, version <b>2.4</b> or later
 716        (2.6 recommended) &nbsp; (package gtk2 and dependencies)</li>
 717  <li> <b>libgnomecanvas</b> version <b>2.4</b> or later &nbsp;
 718        (package libgnomecanvas and dependencies)</li>
 719  <li> <b>libgnomeprint</b> and <b>libgnomeprintui</b> version <b>2.2</b> or later &nbsp;
 720        (packages libgnomeprint22, libgnomeprintui22, and dependencies) </li>
 721 </ul>
 722 </p>
 723 <p>
 724  Additionally:
 725 <ul>
 726  <li> <b>xpdf</b> (more precisely, <b>pdftoppm</b>) is required for PDF file
 727 annotation</li>
 728  <li> <b>ghostscript</b> (optional: used to import PS/PDF files as bitmap
 729  backgrounds)</li>
 730 </ul>
 731 <p>
 732 To compile Xournal, you also need the <b>development packages</b> for the above
 733 libraries (packages gtk2-devel, libgnomecanvas-devel, libgnomeprint22-devel,
 734 libgnomeprintui22-devel, and dependencies), as well as <b>autoconf</b> and
 735 <b>automake</b>.
 736 </p>
 737 <h3 class="subsub">Compilation and installation procedure</h3>
 738 <p>
 739 Download the Xournal distribution tar.gz file, and any needed dependencies.
 740 </p>
 741 <p>
 742 <b>Binary installation in /usr/local:</b><br />
 743 Run (as root) the installer script
 744 <pre>./install-binary</pre> (and upgrade GTK+ and the other libraries if needed).
 745 </p>
 746 <p>
 747 <b>Binary installation in home directory:</b><br />
 748 Run (as any user) the installer script
 749 <pre>./install-binary</pre> (and hope that the required libraries are
 750 installed on your system).
 751 </p>
 752 <p>
 753 <b>Compilation and installation in /usr/local:</b>
 754 <pre>
 755 ./autogen.sh
 756 make
 757 (as root) make install
 758 </pre>
 759 </p>
 760 <p>
 761 <b>Compilation and installation in $HOME:</b>
 762 <pre>
 763 ./autogen.sh
 764 ./configure --prefix=$HOME
 765 make
 766 make install
 767 </pre>
 768 </p>
 769 <p><b>Configure error message:</b> <br />
 770 If autogen.sh generates the error message
 771 &nbsp; &nbsp; <tt><i>
 772 configure: error: Library requirements (gtk+-2.0 >= 2.4.0 libgnomecanvas-2.0 >= 2.4.0 libgnomeprintui-2.2 >= 2.0.0) not met
 773 </i></tt> &nbsp; &nbsp;
 774 even though you have sufficiently recent versions of these libraries on your
 775 system, then you need to install some missing development packages.
 776 </p>
 777 <hr />
 778 <a name="calibration"></a>
 779 <h2 class="subtitle">Tablet calibration issues</h2>
 780 <p>
 781 Configuring the tablet devices properly is unfortunately not as simple as it
 782 ought to be. This is a subject worthy of a detailed how-to document;
 783 meanwhile, here are some hints about how to configure your tablet.
 784 </p>
 785 <h3 class="subsub">Basics</h3>
 786 <p>
 787 Xournal uses the XInput extension to obtain high-resolution coordinates for
 788 strokes drawn using the stylus. If you decide that getting just the right
 789 XInput configuration isn't worth the effort, you can disable XInput features
 790 by unsetting the "Use XInput" option in the Options menu. The price to pay
 791 is a lower graphics quality, as the resolution of all strokes then drops to
 792 1 pixel (instead of the native resolution of the tablet device, which can
 793 be higher by several orders of magnitude).
 794 </p>
 795 <p>
 796 The configuration of tablet devices is controlled in the X server's
 797 configuration file (usually <b>XF86Config</b> or <b>xorg.conf</b> depending on your
 798 distribution). The ServerLayout section should contain lines like:
 799 <pre>
 800 Section "ServerLayout"
 801         ...
 802         InputDevice    "cursor" "SendCoreEvents"
 803         InputDevice    "stylus" "SendCoreEvents"
 804         InputDevice    "eraser" "SendCoreEvents"
 805 EndSection
 806 </pre>
 807 (the last one only if your stylus has an eraser tip), and your configuration
 808 file should include sections such as
 809 <pre>
 810 Section "InputDevice"
 811         Identifier "cursor"
 812         Driver "wacom"
 813         Option "Device" "/dev/ttyS0"
 814         Option "Type" "cursor"
 815         Option "ForceDevice" "ISDV4"
 816         Option "BottomX" "28800"
 817         Option "BottomY" "21760"
 818         Option "Mode" "absolute"
 819 EndSection
 820
 821 Section "InputDevice"
 822         Identifier "stylus"
 823         Driver "wacom"
 824         Option "Device" "/dev/ttyS0"
 825         Option "Type" "stylus"
 826         Option "ForceDevice" "ISDV4"
 827         Option "BottomX" "28800"
 828         Option "BottomY" "21760"
 829         Option "Mode" "absolute"
 830 EndSection
 831
 832 Section "InputDevice"
 833         Identifier "eraser"
 834         Driver "wacom"
 835         Option "Device" "/dev/ttyS0"
 836         Option "Type" "eraser"
 837         Option "ForceDevice" "ISDV4"
 838         Option "BottomX" "28800"
 839         Option "BottomY" "21760"
 840         Option "Mode" "absolute"
 841 EndSection
 842 </pre>
 843 The actual settings will depend on your hardware; look on the web for Linux
 844 installation instructions specific to your model: for example, the
 845 "Device" settings above correspond to a serial port protocol, many tablets
 846 use USB instead; the BottomX and BottomY values correspond to the physical
 847 resolution of the tablet and will vary from one model to another.
 848 </p>
 849 <h3 class="subsub">The cursor doesn't appear in the right place...</h3>
 850 <p>
 851 If the mouse pointer does not follow accurately the position of the stylus,
 852 this is an indication that your tablet is not properly calibrated. If you
 853 have the linuxwacom package, you can try modifying the tablet calibration
 854 using <b>xsetwacom</b>. The relevant parameters are named TopX, BottomX,
 855 TopY, BottomY, and need to be set separately for the stylus and for the
 856 eraser. For example:
 857 <pre>
 858     xsetwacom set stylus TopX 270
 859     xsetwacom set stylus BottomX 28510
 860     ...
 861 </pre>
 862 (the TopX and TopY parameters default to 0 if you haven't set them in your
 863 X server's configuration file). Experiment with these parameters until you
 864 find the right calibration settings for your tablet (i.e., the mouse pointer
 865 appears right under the tip of the stylus).
 866 </p>
 867 <p>
 868 Once you have found the perfect settings for your tablet, update your X
 869 server's configuration file (due to issues with some versions of the
 870 linuxwacom driver, the tablet calibration information is often not updated
 871 properly when using xsetwacom).
 872 </p>
 873 <p>
 874 <b>Important:</b> due to issues with the linuxwacom driver, it is important
 875 to either upgrade your driver to a <a href="manual.html#wacompatch">patched
 876 version</a>, or restrict your choice of settings as follows:
 877 <ul>
 878 <li> your calibration settings should not be changed at runtime (i.e.,
 879 insert your settings directly into your X server configuration file.
 880 Do not add a list of xsetwacom commands to your startup files).
 881 </li>
 882 <li> TopX and TopY values should always be 0.
 883 </li>
 884 </ul>
 885 </p>
 886 <h3 class="subsub">Strokes aren't drawn under the cursor...</h3>
 887 <p>
 888 This is due to misfeatures in the linuxwacom driver. Typically, this
 889 will happen in all of the following cases:
 890 <ul>
 891 <li> the calibration settings have been changed after the X server was
 892 started (using xsetwacom) </li>
 893 <li> the calibration TopX or TopY values are not 0 </li>
 894 <li> the display has been rotated </li>
 895 </ul>
 896 Future versions of the driver may fix these issues. Meanwhile, you can
 897 either disable XInput support in Xournal (in the Options menu), at a
 898 price of a severe loss of resolution (and the eraser tip won't be detected
 899 anymore), or apply this <a href="manual.html#wacompatch">patch</a>
 900 to the wacom driver.
 901 </p>
 902 <p>
 903 I have also had a report that one of the workarounds used by Xournal to
 904 bypass a calibration bug in GTK+ can actually entirely prevent strokes
 905 from being drawn. If you are being unsuccessful at drawing in Xournal
 906 with XInput enabled, try recompiling after changing the first line of
 907 <tt>src/main.c</tt> to
 908 <pre>#define ENABLE_XINPUT_BUGFIX 0</pre>
 909 If this modification does improve things for you, and if you have a bit
 910 of spare time to help investigate the causes of this problem, please
 911 contact me.
 912 </p>
 913 <h3 class="subsub">On-the-fly display rotation</h3>
 914 <p>
 915 You need an X server that supports the RANDR extension, and a
 916 <a href="manual.html#wacompatch">patched</a> version of the linuxwacom
 917 driver to support on-the-fly rotation.
 918 </p>
 919 <p>
 920 To set the tablet in portrait mode:
 921 <pre>
 922   xrandr -o 3
 923   xsetwacom set stylus Rotate cw
 924 </pre>
 925 To return to landscape mode:
 926 <pre>
 927   xrandr -o 0
 928   xsetwacom set stylus Rotate none
 929 </pre>
 930 <b>Note:</b> you should not rotate the display while Xournal is running,
 931 otherwise the tablet calibration in Xournal may (and most likely will)
 932 become incorrect.
 933 Exit Xournal and restart it after the display has been rotated.
 934 </p>
 935 <a name="wacompatch"></a>
 936 <h3 class="subsub">Linuxwacom patch for calibration and rotation</h3>
 937 <p>
 938 This patch fixes rotation and calibration issues with the linuxwacom driver
 939 version 0.7.0.
 940 <ul>
 941 <li>The <a href="http://math.mit.edu/~auroux/software/xournal/linuxwacom-0.7.0-rotate-patch">patch
 942 file</a> for the linuxwacom source code (also included with the Xournal
 943 distribution).</li>
 944 <li>The <a href="http://math.mit.edu/~auroux/software/xournal/linuxwacom-rotate-patch.tar.gz">patched
 945 binaries</a> for the X.org X server.</li>
 946 </ul>
 947 </p>
 948 </body>
 949 </html>