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.4.7
  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://xournal.sourceforge.net/">http://xournal.sourceforge.net/</a> or
  42 <a href="http://math.berkeley.edu/~auroux/software/xournal/">http://math.berkeley.edu/~auroux/software/xournal/</a>
  43 </p>
  44 <p>
  45  Xournal aims to provide superior graphical quality (subpixel resolution) and overall
  46  functionality; however various advanced features have not been implemented
  47  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#configuration">Configuration file</a> </li>
  57   <li> <a href="manual.html#author">Author information, license, bug-reports</a> </li>
  58   <li> <a href="manual.html#changelog">Version history</a> </li>
  59   <li> <a href="manual.html#file-format">The file format</a> </li>
  60   <li> <a href="manual.html#installation">Installation issues</a> and
  61        <a href="manual.html#calibration">tablet calibration issues</a> </li>
  62  </ul>
  63 </p>
  64 <hr />
  65 <a name="getting-started"></a>
  66 <h2 class="subtitle">Getting started</h2>
  67 <p>
  68  Xournal's user interface is (hopefully) intuitive, and if you don't run
  69  into <a href="manual.html#installation">installation</a> or
  70  <a href="manual.html#calibration">tablet calibration</a> issues, you'll
  71  probably be able to start taking notes without referring to this manual.
  72  <br />
  73  Here is a screenshot of the user interface (click to enlarge):
  74 </p>
  75 <p style="text-align: center">
  76  <a href="screenshot.png">
  77    <img src="screenshot.png" style="width: 321px; height: 176px" />
  78  </a>
  79 </p>
  80 <p>
  81 Refer to the next few sections of this manual for more information about
  82 the various functionalities.
  83 </p>
  84 <hr />
  85 <a name="tools"></a>
  86 <h2 class="subtitle">The drawing and selection tools</h2>
  87 <h3 class="subsub"><img src="pixmaps/pencil.png"> The pen</h3>
  88 <p>
  89 The pen is the default drawing tool in Xournal. It comes in a variety
  90 of colors (see the color toolbar buttons and the Color submenu of the
  91 Tools menu) and thicknesses (see the
  92 <a href="manual.html#thicknesses">thickness</a> toolbar buttons and
  93 the Pen Options submenu of the Tools menu).
  94 </p>
  95 <h3 class="subsub"><img src="pixmaps/eraser.png"> The eraser</h3>
  96 <p>
  97 The eraser lets you erase what you have drawn.
  98 By default, stylus buttons 2 and 3 (mouse middle or right buttons) are
  99 mapped to the eraser tool.
 100 <br />
 101 The eraser comes in three different thicknesses (selected using the
 102 <a href="manual.html#thicknesses">thickness</a> toolbar buttons),
 103 and can operate in three different modes (Eraser Options submenu of
 104 the Tools menu):
 105 <ul>
 106  <li>
 107    Standard mode (default): the eraser deletes portions
 108    of strokes previously drawn using the pen or the highlighter.
 109    In this mode, if you erase in the middle of a stroke, the remaining
 110    portions of the stroke are automatically split into shorter strokes.
 111    The background of the page (and the lower layers) are not erased.
 112  </li>
 113  <li>
 114    Whiteout: the eraser is actually a thick white pen, and simply covers
 115    whatever lies underneath, including the background of the page.
 116  </li>
 117  <li>
 118    Delete strokes: whenever the eraser comes in contact with a previously
 119    drawn stroke, the entire stroke is deleted.
 120   </li>
 121 </ul>
 122 </p>
 123 <h3 class="subsub"><img src="pixmaps/highlighter.png"> The highlighter</h3>
 124 <p>
 125   Like the pen, the highlighter comes in a variety of colors (the default
 126   is yellow) and thicknesses. Use the color and thickness toolbar buttons
 127   to change these settings.
 128 </p>
 129 <h3 class="subsub"><img src="pixmaps/text-tool.png"> The text tool</h3>
 130 <p>
 131   To insert a new text item, click at the location where the text is to be
 132   inserted on the page, then type it in or paste it using the contextual
 133   menu (note: no wrapping is performed). To modify a text item, click inside
 134   it. The font and point size can be modified using the "Text Font" command
 135   in the Tools menu (or the toolbar button). The color is the same as that
 136   currently selected for the pen (and can be modified using the toolbar
 137   buttons).
 138 </p>
 139 <p>
 140   Text items can contain arbitrary Unicode characters, provided that a
 141   suitable font is installed on your system. However, languages written
 142   in a direction other than left-to-right might not be handled properly.
 143   If a journal contains some items in a font that is unavailable on your
 144   system, another one will be substituted. (Also, text items will be
 145   lost if the document is opened in a version of Xournal prior to 0.4).
 146   Finally, note that the printing and PDF export features only accept
 147   TrueType and Type 1 scalable fonts (do not use any bitmap fonts), and
 148   that the typesetting of the text may be slightly different in the
 149   printout.
 150 </p>
 151 <h3 class="subsub"> The image tool</h3>
 152 <p>
 153   To insert a new image (from a file on disk), click at the location
 154   where the upper-left corner is to be located. A file selection dialog
 155   box pops up. Alternatively, images can be pasted directly from the
 156   clipboard (without having to select the image tool). In both cases,
 157   the newly inserted image is selected, and can be easily moved or resized
 158   as with any selection.
 159 </p>
 160 <h3 class="subsub"><img src="pixmaps/ruler.png"> The ruler</h3>
 161 <p>
 162   The ruler is not a tool by itself, but rather a special operating mode
 163   of the pen and highlighter tools. When it is enabled, these tools paint
 164   line segments instead of curvy strokes. For simplicity, selecting the
 165   ruler when not in pen or highlighter mode automatically selects the pen.
 166 </p>
 167 <a name="recognizer"></a>
 168 <h3 class="subsub"><img src="pixmaps/shapes.png"> The shape recognizer</h3>
 169 <p>
 170   The shape recognizer is also a special
 171   operating mode of the pen and highlighter tools. When it is enabled,
 172   Xournal attempts to recognize geometric shapes as they are drawn, and
 173   if successful will replace the drawn strokes accordingly. The shapes
 174   that can be recognized are: line segments, circles, rectangles, arrows,
 175   triangles and quadrilaterals. Polygonal shapes can be drawn in a single
 176   stroke or in a sequence of consecutive strokes.
 177 </p>
 178 <p>
 179   The recognizer is set to be as unobtrusive as possible, and should not
 180   interfere too much with handwriting. (It differs in this and other ways
 181   from another shape recognizer written for Xournal by Lukasz Kaiser).
 182   As a result, it may only recognize shapes if you draw them carefully and
 183   deliberately. Specific tips for better recognition: (1) for circles,
 184   a closed curve that isn't quite round works better
 185   than a rounder curve that doesn't close; (2) for arrows, it is better
 186   to lift the pen before drawing the tip of the arrow, and make sure
 187   the tip consists of two straight line segments;
 188   (3) for very elongated rectangles,
 189   recognition tends to be better if you lift the pen between consecutive
 190   sides.
 191 </p>
 192 <h3 class="subsub"><img src="pixmaps/recycled.png"> Default tools</h3>
 193 <p>
 194   Each tool (pen, eraser, highlighter, text) has a default setting
 195   (color, thickness, ... for the drawing tools, font and size for the
 196   text tool) associated to it.
 197   The "Default Pen", "Default Eraser", "Default Highlighter", and
 198   "Default Text" entries of
 199   the Tools menu select the appropriate tool and reset its settings to
 200   the defaults. The toolbar also includes a "Default" button which
 201   resets the currently selected tool to its default settings,
 202   and a "Default Pen" button. <br />
 203   The "Set As Default" entry of the Tools menu takes the current settings
 204   of the currently selected tool and makes them the new default.
 205 </p>
 206 <a name="thicknesses"></a>
 207 <h3 class="subsub"><img src="pixmaps/thin.png"> <img src="pixmaps/medium.png">
 208   <img src="pixmaps/thick.png"> Thickness buttons</h3>
 209 <p>
 210   These three buttons control the thickness of the current drawing tool
 211   (pen, eraser, or highlighter). The thickness can also be adjusted using
 212   the appropriate sub-menu of the Tools menu.
 213 </p>
 214 <h3 class="subsub"><img src="pixmaps/rect-select.png"> Rectangle selection</h3>
 215 <p>
 216   This tool lets you select a rectangular region of the current layer.
 217   All the strokes which are entirely contained within the rectangular region
 218   are selected.
 219   The selection can be moved within its page by clicking inside the
 220   selection rectangle and dragging the cursor. If the cursor is dragged
 221   to a different page, the selection will be moved to the topmost layer of
 222   that page.
 223 </p>
 224 <p>
 225   The selection can be cut, duplicated, etc. (including to a different page
 226   or to a different journal) using the copy-paste toolbar buttons or the
 227   corresponding entries of the Edit menu.
 228 </p>
 229 <h3 class="subsub"><img src="pixmaps/lasso.png"> Lasso selection</h3>
 230 <p>
 231   This tool lets you select an irregular shaped region of the current layer.
 232   All the items which are entirely contained within the given region
 233   are selected. As with the rectangle selection tool, the selection can be moved,
 234   resized, copied and pasted.
 235 </p>
 236 <h3 class="subsub"><img src="pixmaps/stretch.png"> Vertical space</h3>
 237 <p>
 238   This tool lets you insert or remove vertical space within the page:
 239   all the items of the current layer which lie entirely between the cursor
 240   position and the end of the page are moved up or down.
 241 </p>
 242 <p>
 243   Note that the background, and items on other layers, are not affected.
 244   Also, if you insert too much vertical space, some items may fall below
 245   the bottom of the page and become invisible. These items are not lost:
 246   to retrieve them, either use
 247   the vertical space tool again to remove the excess vertical
 248   space, or change the page height to an appropriate value (using the
 249   "Paper Size" entry in the Journal menu).
 250 </p>
 251 <p>
 252   If you drag the cursor below the bottom of the page (so that the
 253   entire block being moved has become invisible), the items will be moved
 254   to the next page (topmost layer); however, any items that were already
 255   present on the next page are left unchanged. Similarly, dragging the
 256   cursor above the top of the page so that the entire block being moved
 257   becomes invisible results in the items being moved to the previous page.
 258 </p>
 259 <h3 class="subsub"><img src="pixmaps/hand.png"> Hand tool</h3>
 260 <p>
 261   This tool lets you browse the journal; dragging the cursor scrolls the
 262   view.
 263 </p>
 264 <h3 class="subsub">Undo and redo</h3>
 265 <p>
 266   All operations performed on the currently open journal (drawing, erasing,
 267   cut-and-paste; adding, deleting, and reformatting pages; etc.) can be
 268   undone and redone at will using the Undo and Redo toolbar buttons or
 269   the corresponding entries in the Edit menu.<br />
 270   There is no limit to the depth of the undo/redo stack. It is cleared only
 271   when you quit the application or open a new journal.
 272 </p>
 273 <a name="mappings"></a>
 274 <h3 class="subsub">Button mappings</h3>
 275 <p>
 276   Stylus buttons 2 and 3 (mouse middle and right buttons) can be mapped
 277   to different tools using the appropriate submenus in the Options menu
 278   (whereas the Tools menu and the toolbar buttons affect the primary tool
 279   assigned to button 1). The default mapping is the eraser.
 280 </p>
 281 <p><b>Advanced configuration:</b>
 282   if a secondary button is mapped to a drawing tool (pen, eraser, or
 283   highlighter), the default is to "dynamically link" its settings to those
 284   of the primary tool, which means that each drawing tool has common
 285   settings (color, thickness, etc.) for all buttons.
 286   Dynamic linking of brush settings
 287   can be disabled by selecting the "Copy of current brush" option in the
 288   "Button mapping" submenu. The settings of the tool for button 2 or 3 are
 289   copied from the button 1 settings at the time when you select the option,
 290   and afterwards they are no longer updated when the button 1 settings are
 291   modified, thus making it possible to assign pens of different colors or
 292   thicknesses to different buttons.
 293 </p>
 294 <p>
 295   Another option that affects button mappings is the "Eraser tip" option.
 296   If this option is turned on and the XInput extensions are enabled, then
 297   the eraser tip of your tablet's stylus will automatically be remapped to
 298   the eraser tool. This behavior, which overrides all other button mappings,
 299   is most useful if your X server is configured to map the eraser tip of
 300   your tablet's stylus to button 1.
 301 </p>
 302 <p>
 303   Also note the "Buttons switch mappings" option, which may be useful to
 304   users of external tablets: when this option is turned on, buttons 2 and 3
 305   only switch the tool mapping, and drawing is still done with button 1.
 306 </p>
 307 <hr />
 308 <a name="pages-layers"></a>
 309 <h2 class="subtitle">Pages, layers, and backgrounds</h2>
 310 <p>
 311 A journal is composed of one or more pages, whose characteristics can be
 312 modified independently of each other. Each page consists of a background
 313 and one or more layers stacked on top of the background. All drawing
 314 operations take place within a single layer, and do not affect the background
 315 or the other layers. You can think of the layers as transparent overlays:
 316 drawing and erasing always takes place on the topmost visible overlay.
 317 <br />
 318 Layers are a convenient mechanism to add temporary annotations on top of a
 319 journal page: because of the logical separation between layers, erasing
 320 in the top layer will not affect the contents of the other layers, and
 321 the top layer can be easily discarded.
 322 </p>
 323 <h3 class="subsub">Navigating the journal</h3>
 324 <p>
 325 The user interface either displays all pages in the journal below each other
 326 ("continuous mode") or a single page ("one-page mode"). You can switch
 327 between the two modes by using the "Continuous" and "One page" entries in
 328 the View menu. The default is the
 329 continuous mode, best adapted to note-taking on multiple pages. The one-page
 330 mode is more appropriate if your journal is a scrapbook in which the pages
 331 have different characteristics (in particular, if you are annotating a
 332 series of pictures of different sizes).
 333 </p>
 334 <p>
 335 You can navigate the journal pages in several different ways:
 336 <ul>
 337  <li> using the navigation toolbar buttons (or the corresponding entries
 338   in the View menu) to go back or forward one page, or to jump to the first
 339   or last page of the journal;
 340  </li>
 341  <li> in continuous mode, scrolling down to the desired page;
 342  </li>
 343  <li> entering a value or using the +/- buttons in the page selection box
 344   at the lower-left corner of the Xournal window.
 345  </li>
 346 </ul>
 347 As a convenient shortcut, going forward one page (or pressing the + button
 348 in the selection box) when already at the end of the journal creates a new
 349 page at the end of the journal.
 350 </p>
 351 <p>
 352 Note: jumping to a page automatically selects the top-most layer in
 353 that page.
 354 </p>
 355 <p>
 356 To navigate the layers of a page, either use the layer selection box at
 357 the bottom of the Xournal window, or use the "Show Layer" and "Hide Layer"
 358 entries in the View menu. The basic rule to remember is that the display
 359 shows all the layers underneath the currently select one, and while those
 360 above it are hidden.
 361 </p>
 362 <p>
 363 Note: the background layer cannot be drawn on; any attempt to draw on the
 364 background will generate an error message and switch back to the first
 365 layer.
 366 </p>
 367 <h3 class="subsub">Managing pages and layers</h3>
 368 <p>
 369 Pages can be added to the journal by using the "New Page ..." entries in
 370 the Journal menu. The newly created page has the same format and background as the
 371 current page (for the "New Page Before" and "New Page After" commands), or
 372 as the last page of the journal (for "New Page At End"). Additionally,
 373 jumping to the next page when already on the last page creates a new page
 374 at the end of the journal.
 375 </p>
 376 <p>
 377 The "Delete Page" entry in the Journal menu removes the current page from
 378 the journal. (Remember that you can always undo this operation if you
 379 deleted a page by accident).
 380 </p>
 381 <p>
 382 The "New Layer" entry in the Journal menu creates a new layer immediately
 383 above the current one, while "Delete Layer" removes the current layer and
 384 its contents (if you attempt to delete the only layer of a page, a new
 385 empty layer will be automatically created).
 386 </p>
 387 <h3 class="subsub">Paper formats and backgrounds</h3>
 388 <p>
 389 The size of the current page can be modified using the "Paper Size" entry
 390 in the Journal menu. Standard and custom sizes are available.
 391 </p>
 392 <p>
 393 The background is either one of several kinds of standard paper types, or a
 394 bitmap image, or a page of a PDF file.
 395 </p>
 396 <p>
 397 To select a <b>standard paper type</b> as background for the current page, use
 398 the "Paper Style" submenu of the Journal menu. The paper color can also
 399 be changed using the "Paper Color" submenu of the Journal menu.
 400 </p>
 401 <p>
 402 To use a <b>PDF file</b> as the background for a journal, see the paragraph
 403 on <a href="manual.html#pdfannotate">PDF annotation</a> below.
 404 </p>
 405 <p>
 406 To load a <b>bitmap image file</b> for use as background for the current page, use
 407 the "Load Background" entry of the Journal menu. This automatically
 408 resizes the current page according to the size of the bitmap image, and
 409 resets the zoom level to 100%. If <i>ghostscript</i> is installed on your
 410 system, you can also use this method to import a fixed-resolution bitmap
 411 version of a Postscript or PDF file; in that case, all pages will be
 412 imported sequentially as backgrounds into consecutive pages (this is
 413 <i>not</i> the
 414 recommended method; PDF annotation is better in every respect).
 415 </p>
 416 <p>
 417 To capture a <b>screenshot</b> of a window or the entire screen and make it
 418 the background of the current page, use the "Background Screenshot" entry of
 419 the Journal menu. This will iconify the Xournal window; click in any window
 420 (after ensuring it is fully visible) to capture its contents, or click on
 421 the desktop (or screen background) to capture the entire screen.
 422 </p>
 423 <p><b>Important note:</b> by default, bitmap images loaded using the "Load
 424 Background" command will not be saved with the journal; instead, the journal
 425 file will contain a reference to the absolute location of the image file.
 426 This means that the background will become unavailable if the image file
 427 is moved or deleted. To avoid this, check the option "Attach file to the
 428 journal" at the bottom of the file selection dialog box.<br />
 429 This option only applies to bitmap image files loaded from disk;
 430 screenshot backgrounds (and bitmaps converted from PS/PDF files using
 431 ghostscript) are automatically "attached" to the journal file: when the
 432 journal is saved, they will be saved (in PNG format) along with it
 433 (using file names of the form *.xoj.bg_*.png).
 434 </p>
 435
 436 <a name="pdfannotate"></a>
 437 <h3 class="subsub">PDF annotation</h3>
 438 <p>
 439 Xournal can be used to annotate PDF files, by loading the pages of a PDF
 440 file as backgrounds for a journal. As of version 0.4.5 this is done using
 441 the <i>poppler</i> library (previous versions used the
 442 <i>pdftoppm</i> converter, which is part of the <i>xpdf</i> utilities or
 443 the <i>poppler</i> utilities depending on distributions).
 444 </p>
 445 <p>
 446 The "Annotate PDF" command in the File menu can be used to load a PDF file
 447 into a new (empty) journal. The page backgrounds and page sizes correspond
 448 to the contents of the PDF file. (Most unencrypted PDF files should be
 449 supported).
 450 </p>
 451 <p>
 452 By default, the PDF file used to generate the backgrounds
 453 will not be saved with the journal; instead, the journal
 454 file will contain a reference to the absolute location of this file.
 455 This means that all backgrounds will become unavailable if the PDF file
 456 is moved or deleted (although Xournal will let you specify
 457 the updated location of the PDF file when opening the journal
 458 file). To avoid this, check the option "Attach file to the journal"
 459 at the bottom of the dialog box when opening the PDF file. The PDF file will
 460 then be saved along with the journal (using a file name of the form
 461 *.xoj.bg.pdf).
 462 <p>
 463 Upon zooming, the page backgrounds are asynchronously updated
 464 to fit the current display resolution. Since this process is quite slow and
 465 memory-intensive, the pages are normally updated only as needed, when they
 466 become visible on the screen (unless you disable the "Progressive
 467 Backgrounds" option in the Options menu). This means that you will
 468 occasionally notice the page backgrounds being updated while you are
 469 scrolling inside the document (at large zoom levels, it can take a while
 470 for the updated background to appear).
 471 <!-- However, since the backgrounds are generated asynchronously by a
 472 separate Unix process, you can keep drawing in the journal
 473 while the update process is still in progress. -->
 474 </p>
 475 <p>
 476 It is strongly recommended that you do not resize PDF pages (using the
 477 "Paper Size" command). This will result in extremely ugly rendering, as
 478 the PDF converter is unable to render bitmaps with
 479 non-standard aspect ratios.
 480 </p>
 481 <p>
 482 While you can perform all sorts of page operations on a journal file
 483 that was created from a PDF file (such as duplicating or deleting pages,
 484 inserting pages with blank or bitmapped backgrounds, ...), it is not
 485 possible to include pages from more than one PDF file into a single journal
 486 document. If you need to annotate two or more PDF files inside a same
 487 journal document, please consider using an external utility for merging
 488 PDF files (for example <i>pdfmerge</i>).
 489 </p>
 490 <p>
 491 <b>Note:</b> the PDF backgrounds are
 492 rescaled and/or regenerated as needed when the zoom level is changed.
 493 Because this consumes a lot of memory and CPU resources, by default this
 494 rescaling is performed on-demand as each page becomes visible. This means
 495 that you will occasionally notice backgrounds being generated while
 496 you are scrolling inside the document (at large zoom levels, this can slow
 497 down the screen refresh rate noticeably). If you'd prefer all backgrounds to
 498 be loaded in advance and rescaled immediately upon changing the zoom level,
 499 disable the "Progressive Backgrounds" option in the Options menu. Be aware
 500 that this increases the memory consumption and will cause out-of-memory
 501 crashes when viewing long documents.
 502 </p>
 503
 504 <hr />
 505 <a name="printing"></a>
 506 <h2 class="subtitle">Printing</h2>
 507 <p>
 508 As of version 0.4.5, Xournal uses the gtk-print architecture for printing
 509 (previous versions used gnome-print). Xournal also includes a native PDF
 510 printing feature.
 511 </p>
 512 <h3 class="subsub">Printing via gtk-print</h3>
 513 <p>
 514 The print dialog box lets you select a printer
 515 (either one of the printers installed on your system, or the "Print to File"
 516 virtual printer), and a range of pages to print (the default is to print
 517 the entire journal). Each page
 518 of the journal is automatically rescaled so as to fit the paper size.
 519 </p>
 520 <p>
 521 Unlike the older gnome-print architecture, gtk-print and poppler make it
 522 possible to efficiently print files that annotate PDF backgrounds. (Prior to
 523 version 0.4.5, PDF backgrounds had to be converted to bitmaps upon printing,
 524 resulting in huge print jobs and low printout quality).
 525 </p>
 526 <p>
 527 The settings are currently not saved properly from one print job to
 528 the next, so make sure to verify the settings.
 529 </p>
 530 <h3 class="subsub">Exporting to PDF</h3>
 531 <p>
 532 Xournal also provides its own PDF rendering
 533 engine. The "Export to PDF" command (in the File menu) produces a
 534 PDF-1.4 file from the currently loaded document. The pages of the
 535 resulting PDF file have the same size as in Xournal. Highlighter strokes
 536 are rendered in a partially transparent manner (note however that
 537 applications such as xpdf and ghostview do not always handle
 538 PDF transparency properly). Text items are rendered by embedding
 539 TrueType subsets or Type 1 fonts into the PDF document as appropriate.
 540 </p>
 541 <p>
 542 Xournal includes a PDF file parser compatible with PDF format
 543 version 1.4; the compression features of PDF 1.5 are
 544 not supported. When exporting a document that uses PDF
 545 backgrounds, Xournal attempts to preserve most of the structure of
 546 the original PDF file (however, auxiliary data such as thumbnails, hyperlinks,
 547 and annotations are lost). If Xournal is unable to parse the PDF
 548 file, the backgrounds are converted to (compressed) bitmaps and a new
 549 PDF file is generated from scratch.
 550 </p>
 551 <hr />
 552 <a name="configuration"></a>
 553 <h2 class="subtitle">Configuration file</h2>
 554 <p>
 555 Xournal's configuration settings are saved to the file
 556 <tt>~user/.xournal/config</tt> by using the "Save
 557 Preferences" command in the Options menu. The settings saved in the
 558 configuration file include in particular:
 559 <ul>
 560 <li>general display preferences: zoom level, window size, ...</li>
 561 <li>default paper settings (as set by the "Set As Default" command in
 562 the Journal menu)</li>
 563 <li>default settings for the pen, eraser, highlighter, and text tools
 564 (as set by the "Set As Default" command in the Tools menu)</li>
 565 <li>mappings for buttons 2 and 3</li>
 566 <li>the various preferences set in the Options menu</li>
 567 </ul>
 568 The configuration file also gives access to additional customization
 569 options which cannot be set from the user interface, such as: the
 570 display resolution in pixels per inch, the step increment in zoom factors,
 571 the tool selected at startup, the thickness of the various drawing tools,
 572 the default directory for opening and saving files, the visibility and
 573 position of the menu and toolbars, ...
 574 </p>
 575 <p>Here is a partial list of configuration file settings:
 576 <ul>
 577 <li> <p><b>Display settings</b> (in the <tt><b>[general]</b></tt> section): <ul>
 578 <li><tt><b>display_dpi:</b></tt>
 579 the display resolution in pixels per inch</li>
 580 <li><tt><b>initial_zoom:</b></tt>
 581 the initial zoom level, in percent</li>
 582 <li><tt><b>window_maximize:</b></tt>
 583 whether to start with a maximized window</li>
 584 <li><tt><b>window_fullscreen:</b></tt>
 585 whether to start in fullscreen mode</li>
 586 <li><tt><b>window_width, window_height:</b></tt>
 587 the preferred window size (if not maximized)</li>
 588 <li><tt><b>zoom_step_factor:</b></tt>
 589 the (multiplicative) factor by which the zoom in/zoom out buttons change the zoom
 590 level</li>
 591 <li><tt><b>view_continuous:</b></tt>
 592 whether to start in continuous or single-page view mode (see also View menu)</li>
 593 <li><tt><b>highlighter_opacity:</b></tt>
 594 the opacity level of highlighter strokes (from 0 to 1; 1 is fully opaque).
 595 Note that .xoj files do not store the opacity level of strokes, so if you
 596 change from the default value of 0.5 your files will look different when
 597 opened on another machine.</li>
 598 </ul></p></li>
 599 <li> <p><b>User interface settings</b> (in the <tt><b>[general]</b></tt> section): <ul>
 600 <li><tt><b>autosave_prefs:</b></tt>
 601 whether to automatically save preferences upon exiting Xournal.</li>
 602 <li><tt><b>interface_order:</b></tt>
 603 the position of the various toolbars relative to the drawing area,
 604 from top to bottom. The default order is: <tt>menu main_toolbar pen_toolbar
 605 drawarea statusbar</tt>. Switching elements around rearranges the
 606 interface. Removing elements from the list hides them.</li>
 607 <li><tt><b>interface_fullscreen:</b></tt>
 608 the same thing, but in fullscreen mode. For example, <tt>drawarea main_toolbar
 609 pen_toolbar</tt> would position the toolbars below the drawing area, and hide
 610 the menu and status bar.
 611 interface.</li>
 612 <li><tt><b>shorten_menus:</b></tt>
 613 whether to hide some little-used menu or toolbar items (see also "Shorten
 614 Menus" in Options menu)</li>
 615 <li><tt><b>shorten_menu_items:</b></tt>
 616 the list of interface items to hide when shorten_menus is enabled. Virtually
 617 everything in the interface can be hidden. A complete list of interface item ID names
 618 can be obtained by running the command <tt>grep id= xournal.glade</tt> in
 619 the base directory of the source code distribution.</li>
 620 <li><tt><b>default_path:</b></tt>
 621 the default path for the open/save dialog boxes (leave blank to use the
 622 current directory)</li>
 623 <li><tt><b>autoload_pdf_xoj:</b></tt>
 624 whether to load filename.pdf.xoj (if it exists) when the user opens
 625 filename.pdf (see also "Autoload .pdf.xoj" in Options menu)</li>
 626 </ul></p></li>
 627 <li> <p><b>Input device settings</b> (in the <tt><b>[general]</b></tt> section): <ul>
 628 <li><tt><b>use_xinput:</b></tt>
 629 whether to enable XInput extensions for high-resolution tablet input
 630 (see also "Use XInput" in Options menu)</li>
 631 <li><tt><b>discard_corepointer:</b></tt>
 632 whether to discard Core events when XInput extensions are enabled. Setting
 633 this to "false" should be safe.</li>
 634 <li><tt><b>use_erasertip:</b></tt>
 635 whether to always map the eraser tip of a stylus to the eraser
 636 (see also "Eraser Tip" in Options menu)</li>
 637 <li><tt><b>buttons_switch_mappings:</b></tt>
 638 whether to have buttons 2 and 3 switch the tool mapping instead of actually
 639 drawing (useful with some external tablets; see also "Buttons Switch
 640 Mappings" in Options menu)</li>
 641 <li><tt><b>pressure_sensitivity:</b></tt>
 642 whether to use stylus pressure to control stroke width (see also "Pressure
 643 Sensitivity" in Options menu)</li>
 644 <li><tt><b>width_minimum_multiplier, width_maximum_multiplier:</b></tt>
 645 the minimum and maximum width multipliers for pressure-sensitive strokes</li>
 646 </ul></p></li>
 647 <li> <p><b>Paper settings</b> (in the <tt><b>[paper]</b></tt> section): <ul>
 648 <li><tt><b>width, height:</b></tt>
 649 the default paper size, in points (1 point = 1/72 in = 0.353 mm)</li>
 650 <li><tt><b>color:</b></tt>
 651 the default paper color (named color or #rrggbbaa)</li>
 652 <li><tt><b>style:</b></tt>
 653 the default paper style (plain, lined, ruled, or graph)</li>
 654 <li><tt><b>apply_all:</b></tt>
 655 whether paper style changes get applied to all pages (see also "Apply to all
 656 pages" in Journal menu)</li>
 657 <li><tt><b>print_ruling:</b></tt>
 658 whether to include the paper ruling lines when printing
 659 (see also "Print Paper Ruling" in Options menu)</li>
 660 <li><tt><b>progressive_bg:</b></tt>
 661 whether to generate PDF backgrounds just-in-time as pages become visible
 662 (rather than immediately upon opening the document or changing the zoom
 663 level, which is more memory-intensive); see also "Progressive Backgrounds"
 664 in Options menu</li>
 665 <li><tt><b>gs_bitmap_dpi:</b></tt>
 666 resolution (in dpi) of bitmap backgrounds generated from PS/PDF files
 667 when using "Load Background" in Journal menu; higher values mean higher
 668 quality but larger memory usage</li>
 669 <li><tt><b>pdftoppm_printing_dpi:</b></tt>
 670 resolution (in dpi) of bitmaps generated from PDF backgrounds when exporting
 671 to PDF (only used if the PDF parser is unable to process the background PDF
 672 file); higher values mean higher quality but larger output files</li>
 673 </ul></p></li>
 674 <li> <p><b>Tool settings</b> (in the <tt><b>[tools]</b></tt> section): <ul>
 675 <li><tt><b>startup_tool:</b></tt>
 676 the tool selected at startup (one of: pen, eraser, highlighter, selectrect,
 677 vertspace, hand)</li>
 678 <li><tt><b>pen_color, pen_thickness, pen_ruler, pen_recognizer:</b></tt>
 679 the default pen settings: color (a named color or #rrggbbaa), thickness
 680 (fine = 1, medium = 2, thick = 3), ruler mode, recognizer mode</li>
 681 <li><tt><b>highlighter_color, highlighter_thickness, highlighter_ruler,
 682 highlighter_recognizer:</b></tt>
 683 the default highlighter settings</li>
 684 <li><tt><b>eraser_thickness, eraser_mode:</b></tt>
 685 the default eraser settings: thickness (fine = 1, medium = 2, thick = 3)
 686 and operating mode (standard = 0, whiteout = 1, delete strokes = 2)</li>
 687 <li><tt><b>btn2_tool, btn3_tool:</b></tt>
 688 the tools mapped to buttons 2 and 3 (can be: pen, eraser, highlighter, selectrect,
 689 vertspace, hand)</li>
 690 <li><tt><b>btn2_linked, btn3_linked:</b></tt>
 691 whether the settings of the tools for buttons 2 and 3 are linked to those of
 692 the corresponding primary tools</li>
 693 <li><tt><b>btn2_color, btn2_thickness, btn2_ruler, btn2_recognizer,
 694 btn2_erasermode:</b></tt>
 695 if the settings are not linked to the primary tool (<tt>btn2_linked</tt> is
 696 false), the settings of the tool mapped to button 2. Not all entries are
 697 applicable, depending on the value of <tt>btn2_tool</tt>.</li>
 698 <li><tt><b>btn3_color, btn3_thickness, btn3_ruler, btn3_recognizer,
 699 btn3_erasermode:</b></tt>
 700 similarly for the button 3 tool.</li>
 701 <li><tt><b>pen_thicknesses, eraser_thicknesses, highlighter_thicknesses:</b></tt>
 702 the widths in points (1 pt = 1/72 in = 0.353 mm) of the various pens
 703 (5 values from 'very fine' to 'very thick'), erasers (3 values from 'fine'
 704 to 'thick') and highlighters (3 values from 'fine' to 'thick') </li>
 705 <li><tt><b>default_font, default_font_size:</b></tt>
 706 the name and point size of the default text font.</li>
 707 </ul></p></li>
 708 </ul>
 709 </p>
 710 <hr />
 711 <a name="author"></a>
 712 <h2 class="subtitle">Author information, license, bug-reports</h2>
 713 <p>
 714 Xournal is written by Denis Auroux
 715 (aur<!--despam-->oux<span>&#x40;</span><span>math</span>&#x2e;<span>berkeley&#x2e;edu).
 716 </p>
 717 <p>
 718 The source code includes contributions by the following people:
 719 Alvaro, Kit Barnes, Eduardo de Barros Lima, Mathieu Bouchard,
 720 Ole J&oslash;rgen Br&oslash;nner, Robert Buchholz, Vincenzo Ciancia, Luca de Cicco,
 721 Michele Codutti, Robert Gerlach, Daniel German, Dirk Gerrits, Simon Guest,
 722 Lukasz Kaiser, Ian Woo Kim, Timo Kluck, David Kolibac, Danny Kukawka,
 723 Stefan Lembach, Bob McElrath, Andy Neitzke, David Planella, Marco Poletti,
 724 Alex Ray, Jean-Baptiste Rouquier, Victor Saase, Marco Souza, Mike Ter Louw,
 725 Uwe Winter, Lu Zhihe.
 726 </p>
 727 <p style="font-size:0.9em">(Let me know if you are missing from this list or
 728 if your name is mis-spelled)</p>
 729 <p>
 730 Xournal is distributed under the GNU General Public License (version 2, or
 731 at your option any later version).
 732 </p>
 733 <p style="font-size: 0.9em; font-style: italic">
 734  <b>Note:</b> most of the code of version 0.4.2.1
 735  (excluding graphics and a few portions of the code) has also been released
 736  under the MIT License. Please contact the main developer if
 737  you need an MIT License version of the 0.4.2.1 code. Later versions are
 738  not available under MIT License.
 739 </p>
 740 <p>Feel free to contact me with bug reports and suggestions; I apologize
 741 in advance if I am unable to respond properly to some requests.
 742 If you find a sequence of operations which crashes Xournal in a reproducible
 743 manner, please send detailed instructions on how to reproduce the crash.
 744 A core file may also be helpful.
 745 </p>
 746 <p>
 747 Bug reports and suggestions can also be submitted on Xournal's
 748 <a href="http://www.sourceforge.net/projects/xournal/">SourceForge page.</a>
 749 </p>
 750 <hr />
 751 <a name="changelog"></a>
 752 <h2 class="subtitle">Version history</h2>
 753 <p>
 754 Version 0.4.7 (July 4, 2012):
 755 <ul>
 756      <li>insert image tool (based on patches by Victor Saase and Simon Guest)
 757 </li><li>renamed "Journal" menu to "Page"
 758 </li><li>paste images and text directly from and to other applications
 759 </li><li>lasso tool (based on patch by Ian Woo Kim)
 760 </ul>
 761 </p>
 762 <p>
 763 Version 0.4.6 (May 22, 2012):
 764 <ul>
 765      <li>win32 portability code (contributed by Dirk Gerrits)
 766 </li><li>fix bug in PDF export code on 64-bit systems (patch by Robert Buchholz)
 767 </li><li>fix hand tool bug when exiting canvas (#2905711)
 768 </li><li>Italian translation (Marco Poletti), German translation (Stefan Lembach)
 769 </li><li>Spanish translation (Alvaro), Brazil Portuguese translation (Marco Souza)
 770 </li><li>fix save bug with text boxes containing &gt; 4095 characters
 771 </li><li>Czech translation (David Kolibac), Dutch translation (Timo Kluck)
 772 </li><li>fix crash upon unplugging input devices
 773 </li><li>change close dialog box default to "save" (patch by Kit Barnes)
 774 </li><li>option to force PDF background rendering via cairo (slower but nicer)
 775 </li><li>wrapper for missing GdkPixbuf rendering function in newest poppler
 776 </li><li>disable GTK+ XInput bugfix by default (#3429416)
 777 </li><li>fix linker flags (#3208984); evdev coordinate fix (#3244118) (Timo Kluck)
 778 </li><li>specify license version: GPL v2 or later
 779 </li><li>fix 1.#J coordinates from win32 xoj files
 780 </li>
 781 </ul>
 782 </p>
 783 <p>
 784 Version 0.4.5 (Oct 2, 2009):
 785 <ul>
 786      <li>bugfixes for GTK+ 2.16/2.17 issues with xinput events
 787 </li><li>various minor UI bugfixes
 788 </li><li>gettext internationalization (contributed by David Planella)
 789 </li><li>Catalan translation (by David Planella), French translation
 790 </li><li>use poppler instead of pdftoppm to render PDF backgrounds
 791     (after patches by Mike Ter Louw and Bob McElrath)
 792 </li><li>various improvements to UI and to key bindings (including
 793     patches by Bob McElrath and Lu Zhihe)
 794 </li><li>use gtk-print instead of libgnomeprint for printing
 795 </li><li>custom color chooser (patch contributed by Alex Ray)
 796 </li><li>option to have tablet buttons toggle the mapping rather than draw
 797 </li><li>paper color chooser (after a patch by Ole Joergen Broenner)
 798 </li><li>remove binary installer (due to binary incompatibilities)
 799 </li><li>UPDATED DEPENDENCIES: need gtk+ 2.10, poppler-glib 0.5.4
 800 </li>
 801 </ul>
 802 </p>
 803 <p>
 804 Version 0.4.2.1 (Mar 27, 2008):
 805 <ul>
 806  <li>bugfix for #1926757 (crash upon pasting variable-width stroke)</li>
 807  <li>bugfix: set ruler/recognizer setting to default upon switching tools</li>
 808 </ul>
 809 </p>
 810 <p>
 811 Version 0.4.2 (Mar 25, 2008):
 812 <ul>
 813  <li>bugfixes for X.org 7.3; allow XInput and core events in reverse order</li>
 814  <li>resize selection (patch contributed by Andy Neitzke)</li>
 815  <li>pressure sensitive pen (variable stroke width) (patch by Andy Neitzke)</li>
 816  <li>geometric shape recognizer (after an idea by Lukasz Kaiser)
 817      (see <a href="manual.html#recognizer">here</a>)</li>
 818  <li>clean up compiler warnings (patch contributed by Danny Kukawka)</li>
 819 </ul>
 820 </p>
 821 <p>
 822 Version 0.4.1 (Sep 15, 2007):
 823 <ul>
 824  <li> bugfix: compatibility with new versions of pdftoppm (thanks to
 825       Vincenzo Ciancia)</li>
 826  <li>GTK+ 2.11 event processing bugfix</li>
 827  <li>minor bugfixes: hand tool, handling of filenames containing '&amp;'</li>
 828  <li>desktop and MIME files (thanks to Mathieu Bouchard) + updated installer</li>
 829  <li>config options: left-handed scrollbar (contributed by Uwe Winter),
 830      hide some menu items (customizable in config file), auto-save
 831      preferences</li>
 832 </ul>
 833 </p>
 834 <p>
 835 Version 0.4.0.1 (September 3, 2007):
 836 <ul>
 837  <li>bugfixes for GTK+ 2.11 behavior (thanks to everyone who reported bugs)</li>
 838 </ul>
 839 </p>
 840 <p>
 841 Version 0.4 (August 15, 2007):
 842 <ul>
 843  <li>text tool (handles most TrueType and Type1 fonts)</li>
 844  <li>font selection dialog and button</li>
 845  <li>keyboard mappings (arrow keys)</li>
 846  <li>menu mnemonics and shortcuts (suggestions by Jean-Baptiste Rouquier)</li>
 847  <li>more responsive hand tool</li>
 848  <li>bugfix for GTK+ 2.11 XInput behavior (thanks to Robert Gerlach)</li>
 849  <li>various minor bugfixes and enhancements</li>
 850 </ul>
 851 </p>
 852 <p>
 853 Version 0.3.3 (January 31, 2007):
 854 <ul>
 855  <li>bugfix: upon loading a new file, zoom is set to default startup zoom</li>
 856  <li>config option to allow input from a mouse or other core pointer device</li>
 857  <li>config file entry to specify a default location for open/save
 858      (patch contributed by Andy Neitzke)</li>
 859  <li>config file entries to customize visibility and position of toolbars</li>
 860  <li>icon (thanks to Michele Codutti)</li>
 861 </ul>
 862 </p>
 863 <p>
 864 Version 0.3.2 (November 25, 2006):
 865 <ul>
 866  <li>preferences file and Save Preferences command</li>
 867  <li>extra customization (via preferences file)</li>
 868  <li>minor UI changes (patch contributed by Eduardo de Barros Lima)</li>
 869  <li>hand tool (partially contributed by Vincenzo Ciancia)</li>
 870  <li>a few bugfixes in rendering of bitmap backgrounds</li>
 871 </ul>
 872 <p>
 873 Version 0.3.1 (August 3, 2006):
 874 <ul>
 875  <li>fixed a file format bug on systems with non-standard numeric locale
 876      (bug reported by Gert Renckens)</li>
 877 </ul>
 878 </p>
 879 <p>
 880 Version 0.3 (July 23, 2006):
 881 <ul>
 882  <li>new PDF rendering engine: export to PDF generates optimized files
 883    (smaller and more accurate)</li>
 884  <li>export to PDF handles PDF backgrounds (up to PDF-1.4) natively
 885     (without conversion to bitmap)</li>
 886  <li>default thickness of erasers and highlighters slightly increased</li>
 887  <li>zoom dialog box with input box and "fit to page height" option</li>
 888  <li>file format documentation added to the user's manual</li>
 889 </ul>
 890 </p>
 891 <p>
 892 Version 0.2.2 (June 5, 2006):
 893 <ul>
 894  <li>mapping of tools to stylus buttons (the options menu has new entries
 895     to allow the mapping of buttons 2 and 3 to arbitrary tools; the tools
 896     menu and toolbar affect the settings for button 1)
 897     (see <a href="manual.html#mappings">here</a>)</li>
 898  <li>moving selection by drag-and-drop works across page boundaries</li>
 899  <li>vertical space tool can move items to next page (only when the entire
 900     block being moved has crossed the page boundary; items on the new page
 901     are not moved)</li>
 902  <li>"apply to all pages" is now a toggle button affecting the behavior of
 903     paper size, color, and style commands</li>
 904  <li>change in the behavior of the selection upon switching between tools</li>
 905 </ul>
 906 </p>
 907 <p>
 908 Version 0.2.1 (June 3, 2006):
 909 <ul>
 910  <li>recently used files listed in file menu</li>
 911  <li>can change color or thickness of pen strokes in selection</li>
 912  <li>function to apply paper style to all pages</li>
 913  <li>can specify on command line a PDF file to annotate</li>
 914  <li>suggest a derived file name for PDF annotation</li>
 915  <li>speed up switching between pages</li>
 916  <li>fixed a bug in XInput initialization (thanks to Luca de Cicco)</li>
 917  <li>fixed a bug in print ranges (thanks to Mathieu Bouchard)</li>
 918  <li>fixed a refresh bug in rescaling bitmap backgrounds</li>
 919 </ul>
 920 </p>
 921 <p>
 922 Version 0.2 (January 29, 2006):
 923 <ul>
 924  <li>PDF file annotation using xpdf's pdftoppm
 925       (PDF backgrounds updated asynchronously at all resolutions)</li>
 926  <li>PS/PDF backgrounds (as bitmaps at fixed resolution) using ghostscript</li>
 927  <li>option to antialias and filter bitmap backgrounds when zooming</li>
 928  <li>option to emulate eraser tip with right mouse button</li>
 929  <li>binary installer allows non-root installation without compiling</li>
 930  <li>full-screen mode (patch contributed by Luca De Cicco)</li>
 931 </ul>
 932 </p>
 933 <p>
 934 Version 0.1.1 (January 5, 2006):
 935 <ul>
 936  <li> two bugfixes </li>
 937  <li> backward compatibility with GTK+ 2.4 </li>
 938 </ul>
 939 </p>
 940 <p>
 941 Version 0.1 (January 2, 2006): initial release.
 942 </p>
 943 <hr />
 944 <a name="file-format"></a>
 945 <h2 class="subtitle">The file format</h2>
 946 <h3 class="subsub">Overall structure</h3>
 947 <p>
 948 Xournal stores its data in gzipped XML-like files. The gzipped data consists
 949 of a succession of XML tags describing the document. By convention, the
 950 file header and trailer look like this:
 951 <pre>
 952 &lt;?xml version="1.0" standalone="no"?&gt;
 953 &lt;xournal version="..."&gt;
 954 &lt;title&gt;Xournal document - see http://math.mit.edu/~auroux/software/xournal/&lt;/title&gt;
 955 ... sequence of pages ...
 956 &lt;/xournal&gt;
 957 </pre>
 958 The &lt;title&gt; and &lt;xournal&gt; tags may only appear within the file
 959 header (not within the pages of the document). The <i>version</i> attribute of
 960 the &lt;xournal&gt; tag indicates which version of Xournal was used to
 961 create the document; it is currently ignored, but may be used in a later
 962 release if the file format changes in an incompatible manner.
 963 (Following a suggestion of Matteo Abrate, starting with version 0.4 the
 964 &lt;xournal&gt; tag is the document's root tag, and encloses all other tags).
 965 </p>
 966 <p>
 967 The rest of the file is a sequence of pages, specified by a
 968 &lt;page&gt; tag, whose attributes <i>width</i> and <i>height</i> specify the
 969 physical size of the page in points (1/72 in). The width and height
 970 parameters are floating point values. The format of a page is therefore:
 971 <pre>
 972 &lt;page width="..." height="..."&gt;
 973 ... page contents ...
 974 &lt;/page&gt;
 975 </pre>
 976 </p>
 977 <h3 class="subsub">Page background</h3>
 978 <p>
 979 The first entry within a page describes the page background.
 980 It consists of a &lt;background&gt; tag followed by several mandatory
 981 XML attributes. The first attribute is always <i>type</i>, which
 982 can take three possible values: "solid" for a solid background, "pixmap"
 983 for a bitmap background, and "pdf" if the background is a page of a PDF
 984 document. The rest of the attributes depends on the type of background.
 985 <ul>
 986 <li><p> Solid background: <tt>&lt;background type="solid" color="..."
 987 style="..." /&gt;</tt> <br />The <i>color</i> attribute takes one of
 988 the standard values "white", "yellow", "pink", "orange", "blue", "green",
 989 or can specify a hexadecimal RGBA value in the format "#rrggbbaa". The
 990 <i>style</i> attribute takes one of the standard values "plain", "lined",
 991 "ruled", or "graph".</p>
 992 </li>
 993 <li><p> Bitmap background: <tt>&lt;background type="pixmap" domain="..."
 994 filename="..." /&gt;</tt> <br />
 995 The <i>domain</i> attribute takes one of the standard values "absolute",
 996 "attach", or "clone". A value of "absolute" indicates that the bitmap is
 997 found in the file specified by <i>filename</i>. The bitmap can be in any
 998 format recognized by the gdk-pixbuf library; this includes most of the
 999 common bitmap formats (JPEG, PNG, BMP, GIF, PCX, PNM, TIFF, ...).
1000 <br />A value
1001 of "attach" indicates that the bitmap is an attachment to the Xournal file.
1002 The bitmap is in PNG format, and resides in a file whose name is derived
1003 from that of the main Xournal file by appending to it a dot and the contents
1004 of the <i>filename</i> attribute. For example, if the Xournal file is in
1005 <tt>file.xoj</tt> and the <i>filename</i> attribute is <tt>"bg_1.png"</tt>
1006 then the bitmap file is <tt>file.xoj.bg_1.png</tt> (Xournal saves attached
1007 bitmaps sequentially in files ...bg_1.png, ...bg_2.png, etc.)
1008 <br />A value of "clone" indicates that the bitmap is identical to the
1009 background of a previous page of the journal; the <i>filename</i> attribute
1010 then specifies the page number, starting with 0 for the first page. For
1011 example, if a <i>filename</i> value of <tt>"1"</tt> indicates that the
1012 background bitmap is identical to that of the second page.
1013 </p>
1014 </li>
1015 <li><p> PDF background: <tt>&lt;background type="pdf" domain="..."
1016 filename="..." pageno="..." /&gt;</tt> or
1017 <tt>&lt;background type="pdf" pageno="..." /&gt;</tt>
1018 <br />The <i>domain</i> and <i>filename</i> attributes must be specified
1019 for the first page of the journal that uses a PDF background, and must
1020 be omitted subsequently for every other page that uses a PDF background.
1021 The <i>domain</i> attribute takes one of the standard values
1022 "absolute" and "attach"; the PDF document is to be found in the file
1023 specified by <i>filename</i> (if <i>domain</i> is "absolute"), or in the
1024 file whose name is obtained by appending a dot and the contents of the
1025 <i>filename</i> attribute to the name of the main Xournal file (if
1026 <i>domain</i> is "attach"). The <i>pageno</i> attribute specifies which
1027 page of the PDF file is used as background, starting with 1 for the first
1028 page of the PDF file.
1029 </p>
1030 </li>
1031 </ul>
1032 </p>
1033 <h3 class="subsub">Layers and strokes</h3>
1034 <p>
1035 After the line specifying the background, the remainder of a &lt;page&gt;
1036 section is occupied by one or more layer sections
1037 <pre>&lt;layer&gt; ... &lt;/layer&gt;</pre>
1038 describing the various items within a layer. Every page must
1039 contain at least one layer; a layer may be empty. The successive layers
1040 are listed in their stacking order, from bottom to top.
1041 </p>
1042 <p>
1043 A layer consists of a collection of items, listed in the order in which
1044 they should be drawn
1045 (from bottom-most to top-most).
1046 Up to version 0.3.3, the only legal contents within a layer are
1047 strokes. The format of a stroke is:
1048 <pre>&lt;stroke tool="..." color="..." width="..."&gt;
1049 ... list of coordinates ...
1050 &lt;/stroke&gt;
1051 </pre>
1052 The <i>tool</i> attribute can take the values "pen", "highlighter", or
1053 "eraser" depending on the tool used to create the stroke (pen, highlighter,
1054 or whiteout eraser); a value of "highlighter" indicates that the stroke
1055 should be painted in a partially transparent manner (Xournal uses an alpha
1056 coefficient of 0.5).
1057 </p>
1058 <p>
1059 The <i>color</i> attribute can take one of the standard values "black",
1060 "blue", "red", "green", "gray", "lightblue", "lightgreen", "magenta",
1061 "orange", "yellow", "white", or can specify a hexadecimal RGBA value in
1062 the format "#rrggbbaa".
1063 </p>
1064 <p>
1065 The <i>width</i> attribute is a floating-point
1066 number (or a sequence of floating-point numbers starting with version 0.4.2),
1067 and specifies the width of the stroke in points (1/72 in). (For a
1068 variable-width stroke, the <i>width</i> attribute contains a
1069 whitespace-separated succession of floating-point values: first the
1070 nominal brush width, and then the width of each successive segment forming
1071 the stroke.)
1072 </p>
1073 <p>
1074 The list of coordinates is simply a succession of floating-point values,
1075 separated by whitespace.
1076 The number of given values must be even; consecutive pairs of values give
1077 the <i>x</i> and <i>y</i> coordinates of each point along the stroke.
1078 These values are expressed in points (1/72 in). The coordinates (0,0)
1079 represent the top-left corner of the page: hence x is measured from the left
1080 of the page, and y is measured from the top of the page.
1081 </p>
1082 <p>
1083 Every stroke must contain at least two points (four floating point values).
1084 Moreover, two consecutive points on the stroke should be spaced no more
1085 than 5 units apart or so; longer line segments should be subdivided as
1086 appropriate (otherwise the eraser tool will not interact properly with the
1087 stroke). The default precision used by Xournal for the x,y coordinates is
1088 0.01 unit (1/7200 in).
1089 </p>
1090 <p>Starting with version 0.4, layers also contain text items.
1091 The format of a text item is:
1092 <pre>&lt;text font="..." size="..." x="..." y="..." color="..."&gt;... text ...&lt;/text&gt;
1093 </pre>
1094 The <i>font</i> attribute contains the font name, for example "Serif Bold
1095 Italic"; if the font is not available, another font will be substituted.
1096 The <i>size</i> attribute specifies the font size in points. The <i>x</i>
1097 and <i>y</i> attributes specify the coordinates of the top-left corner
1098 of the text box in page coordinates (measured in points from the top-left
1099 corner of the page). Finally, the <i>color</i> attribute contains either
1100 the name of a standard color or a hexadecimal RGBA value (see above).
1101 </p>
1102 <p>
1103 The contents of the text are encoded in UTF-8, with the characters
1104 <tt>'&amp;', '&lt;', '&gt;'</tt> replaced by <tt>&amp;amp;, &amp;lt;,
1105 &amp;gt;</tt>. Whitespace and linefeeds are preserved (in particular,
1106 no extraneous whitespace should be inserted between the enclosing tags
1107 and the text itself).
1108 </p>
1109 <p>Starting with version 0.4.7, layers can also contain image items.
1110 The format of an image item is:
1111 <pre>&lt;image left="..." top="..." right="..." bottom="..."&gt;... data ...&lt;/image&gt;
1112 </pre>
1113 The <i>left</i>, <i>top</i>, <i>right</i> and <i>bottom</i> attributes
1114 specify the bounding box to which the image is scaled, in page coordinates
1115 (measured in points from the top-left corner). The data is in base64-encoded
1116 PNG format (though any other base64-encoded format that can be loaded by
1117 gdk-pixbuf is currently accepted).
1118 <hr />
1119 <a name="installation"></a>
1120 <h2 class="subtitle">Installation issues</h2>
1121 <h3 class="subsub">Dependencies</h3>
1122 <p>
1123 The following libraries are required to run Xournal (they are standard on
1124 modern Linux distributions such as Fedora 6 or later, RHEL 5 or
1125 later, Ubuntu 6.10 or later, etc.):
1126 <ul>
1127  <li> the <b>gtk+</b> libraries, version <b>2.10</b> or later
1128  (package gtk2 and dependencies)</li>
1129  <li> <b>libgnomecanvas</b> version <b>2.4</b> or later &nbsp;
1130  (package libgnomecanvas and dependencies)</li>
1131  <li> <b>poppler-glib</b> version <b>0.5.4</b> or later &nbsp;
1132  (package poppler-glib and dependencies)</li>
1133 </ul>
1134 </p>
1135 <p>
1136  Optional:
1137 <ul>
1138  <li> ghostscript (optional: used to import PS/PDF files as bitmap
1139  backgrounds)</li>
1140 </ul>
1141 <p>
1142 To compile Xournal, you also need the <b>development packages</b> for the above
1143 libraries (packages gtk2-devel, libgnomecanvas-devel, poppler-glib-devel,
1144 and dependencies), as well as <b>autoconf</b> and
1145 <b>automake</b>.
1146 </p>
1147 <h3 class="subsub">Compilation and installation procedure</h3>
1148 <p>
1149 Download the Xournal distribution tar.gz file, and any needed dependencies.
1150 </p>
1151 <p>
1152 <b>Compilation and installation in /usr/local:</b>
1153 <pre>
1154 ./autogen.sh
1155 make
1156 (as root) make install
1157 (as root) make desktop-install
1158 </pre>
1159 </p>
1160 <p>
1161 <b>Compilation and installation in $HOME:</b>
1162 <pre>
1163 ./autogen.sh
1164 ./configure --prefix=$HOME
1165 make
1166 make install
1167 make home-desktop-install
1168 </pre>
1169 </p>
1170 <p><b>Configure error message:</b> <br />
1171 If configure generates the error message
1172 &nbsp; &nbsp; <tt><i>
1173 configure: error: Package requirements (gtk+-2.0 >= 2.10.0
1174 libgnomecanvas-2.0 >= 2.4.0 poppler-glib >= 0.5.4)  not met
1175 </i></tt> &nbsp; &nbsp;
1176 even though you have sufficiently recent versions of these libraries on your
1177 system, then you need to install some missing development packages.
1178 </p>
1179 <hr />
1180 <a name="calibration"></a>
1181 <h2 class="subtitle">Tablet calibration issues</h2>
1182 <p>
1183 Configuring the tablet devices properly is unfortunately not as simple as it
1184 ought to be. This is a subject worthy of a detailed how-to document;
1185 meanwhile, here are some hints about how to configure your tablet.
1186 </p>
1187 <h3 class="subsub">Basics</h3>
1188 <p>
1189 Xournal uses the XInput extension to obtain high-resolution coordinates for
1190 strokes drawn using the stylus. If you decide that getting just the right
1191 XInput configuration isn't worth the effort, you can disable XInput features
1192 by unsetting the "Use XInput" option in the Options menu. The price to pay
1193 is a lower graphics quality, as the resolution of all strokes then drops to
1194 1 pixel (instead of the native resolution of the tablet device, which can
1195 be higher by several orders of magnitude).
1196 </p>
1197 <p>
1198 The configuration of tablet devices is controlled in the X server's
1199 configuration file (usually <b>/etc/X11/xorg.conf</b> depending on your
1200 distribution). The latest X servers can detect a tablet automatically and
1201 do not require the presence of xorg.conf to work properly; so recent
1202 distributions typically no longer includde such a file. However, if
1203 auto-configuration fails, you can always create a xorg.conf that explicitly
1204 specifies tablet devices.
1205 </p>
1206 <p>
1207 Assuming you do have a xorg.conf, the ServerLayout section should contain lines like:
1208 <pre>
1209 Section "ServerLayout"
1210         ...
1211         InputDevice    "cursor" "SendCoreEvents"
1212         InputDevice    "stylus" "SendCoreEvents"
1213         InputDevice    "eraser" "SendCoreEvents"
1214 EndSection
1215 </pre>
1216 (the last one only if your stylus has an eraser tip), and your configuration
1217 file should include sections such as
1218 <pre>
1219 Section "InputDevice"
1220         Identifier "cursor"
1221         Driver "wacom"
1222         Option "Device" "/dev/ttyS0"
1223         Option "Type" "cursor"
1224         Option "ForceDevice" "ISDV4"
1225         Option "BottomX" "28800"
1226         Option "BottomY" "21760"
1227         Option "Mode" "absolute"
1228 EndSection
1229
1230 Section "InputDevice"
1231         Identifier "stylus"
1232         Driver "wacom"
1233         Option "Device" "/dev/ttyS0"
1234         Option "Type" "stylus"
1235         Option "ForceDevice" "ISDV4"
1236         Option "BottomX" "28800"
1237         Option "BottomY" "21760"
1238         Option "Mode" "absolute"
1239 EndSection
1240
1241 Section "InputDevice"
1242         Identifier "eraser"
1243         Driver "wacom"
1244         Option "Device" "/dev/ttyS0"
1245         Option "Type" "eraser"
1246         Option "ForceDevice" "ISDV4"
1247         Option "BottomX" "28800"
1248         Option "BottomY" "21760"
1249         Option "Mode" "absolute"
1250 EndSection
1251 </pre>
1252 The actual settings will depend on your hardware; look on the web for Linux
1253 installation instructions specific to your model: for example, the
1254 "Device" settings above correspond to a serial port protocol, many tablets
1255 use USB instead; the BottomX and BottomY values correspond to the physical
1256 resolution of the tablet and will vary from one model to another.
1257 </p>
1258 <p>
1259 For historical reasons, most X servers do not allow the input device
1260 designated as the "core pointer" in the X server's configuration file
1261 to be used as an XInput extension device. Thus, your tablet input devices
1262 should <b>not</b> be designated as the core pointer device. Instead, they
1263 should be configured with the "SendCoreEvents" option, which enables them
1264 to simultaneously generate XInput extension events and move the cursor on
1265 the screen.
1266 </p>
1267 <p>
1268 <b>If you have a newer X server</b> and no xorg.conf file, the input devices can be
1269 configured using the <i>xinput</i> command.
1270 </p>
1271 <p>
1272 <b>Note:</b> with older X servers, only tablet devices are XInput devices, while
1273 a built-in pointing device or an external mouse would only act as the core
1274 pointer. In newer X servers, all devices are handled through XInput (even
1275 though without advanced capabilities), though mice and touchpads typically
1276 send invalid event data. Xournal tries to work around the most common bugs
1277 in input device drivers and GTK+ input event processing.
1278 </p>
1279 <h3 class="subsub">The cursor doesn't appear in the right place...</h3>
1280 <p>
1281 If the mouse pointer does not follow accurately the position of the stylus,
1282 this is an indication that your tablet is not properly calibrated. If you
1283 have the linuxwacom package, you can try modifying the tablet calibration
1284 using <b>xsetwacom</b>. The relevant parameters are named TopX, BottomX,
1285 TopY, BottomY, and need to be set separately for the stylus and for the
1286 eraser. For example:
1287 <pre>
1288     xsetwacom set stylus TopX 270
1289     xsetwacom set stylus BottomX 28510
1290     ...
1291 </pre>
1292 (the TopX and TopY parameters default to 0 if you haven't set them in your
1293 X server's configuration file). Experiment with these parameters until you
1294 find the right calibration settings for your tablet (i.e., the mouse pointer
1295 appears right under the tip of the stylus).
1296 </p>
1297 <p>
1298 Once you have found the perfect settings for your tablet, update your X
1299 server's configuration file or startup scripts.
1300 </p>
1301 <p>
1302 <b>Important:</b> on older systems, the TopX and TopY values should always
1303 be kept at 0 to avoid calibration bugs.
1304 </p>
1305 <h3 class="subsub">The cursor is in the right place, but strokes aren't
1306 drawn under the cursor...</h3>
1307 <p>
1308 If you experience this while trying to draw with a mouse, touchpad, or other
1309 non-tablet device:
1310 <ul>
1311 <li> If you don't have a tablet, simply disable "Use XInput" in the Options
1312 menu, this is the fastest way of fixing the problem.</li>
1313 <li> Upgrade to a recent version of Xournal (0.4.5 or later). Older versions
1314 of Xournal are not compatible with the event handling code of recent X server
1315 and GTK+ library versions.</li>
1316 <li> Check that the "Discard Core Events" option is disabled
1317 (<tt>discard_corepointer</tt> should be set to <tt>false</tt> in
1318 ~/.xournal/config).</li>
1319 </ul>
1320 If you experience this while trying to draw with a tablet pen:
1321 <ul>
1322 <li> If you are using an obsolete version of the linuxwacom driver (before
1323 0.7.6) or of GTK+, please upgrade your system.</li>
1324 <li>If you are using GTK+ 2.17 or newer, please upgrade to Xournal 0.4.5 or
1325 later. The input event processing behavior of GTK+ has changed and is no
1326 longer compatible with older versions of Xournal.</li>
1327 <li> The display geometry might have changed since the beginning of your
1328 session in Xournal
1329 (resolution changed, external monitor connected, display rotated, etc.).
1330 You need to exit Xournal and re-start it each time your display
1331 configuration changes.</li>
1332 <li> Your tablet devices might be incorrectly calibrated or configured.</li>
1333 </ul>
1334 If all else fails, you can disable XInput support in Xournal (in the
1335 Options menu), at a price of a severe loss of resolution (and the eraser tip
1336 won't be detected anymore).
1337 </p>
1338 <p>
1339 One of the workarounds used by Xournal to
1340 bypass a calibration bug in old versions of GTK+ seems to be more harmful
1341 than helpful with modern distributions. If you miss the old behavior or
1342 are having XInput issues, try recompiling after uncommenting the line
1343 <pre>#define ENABLE_XINPUT_BUGFIX</pre>
1344 near the beginning of <tt>src/xournal.h</tt>.
1345 </p>
1346 <h3 class="subsub">On-the-fly display rotation</h3>
1347 <p>
1348 You need an X server that supports the RANDR extension, and a sufficiently
1349 recent (0.7.6 or later)
1350 version of the linuxwacom driver to support on-the-fly rotation.
1351 </p>
1352 <p>
1353 To set the tablet in portrait mode:
1354 <pre>
1355   xrandr -o 3
1356   xsetwacom set stylus Rotate cw
1357 </pre>
1358 To return to landscape mode:
1359 <pre>
1360   xrandr -o 0
1361   xsetwacom set stylus Rotate none
1362 </pre>
1363 <b>Note #1:</b> you should not rotate the display while Xournal is running,
1364 otherwise the tablet calibration in Xournal may (and most likely will)
1365 become incorrect. (Less likely to occur with modern distributions and
1366 ENABLE_XINPUT_BUGFIX disabled).
1367 Exit Xournal and restart it after the display has been rotated.
1368 </p>
1369 <p>
1370 <b>Note #2:</b> the syntax of xrandr commands has changed in newer X servers.
1371 Consult the xrandr manual page for the new syntax.
1372 </body>
1373 </html>