Bugfixes: release 0.4.2.1.

[xournal.git] / html-doc / manual.html

diff --git a/html-doc/manual.html b/html-doc/manual.html
index a7bfcc44a0bc3d1ccc2957641cf92955fb9811f2..ce3edc14dfdb381dbc087f196e9a02286fbce4e7 100644 (file)
--- a/html-doc/manual.html
+++ b/html-doc/manual.html
@@ -24,7 +24,7 @@
   Xournal User's Manual
 </h2>
 <p style="font-size: 0.95em; text-align: center; color: rgb(0,0,0)">
   Xournal User's Manual
 </h2>
 <p style="font-size: 0.95em; text-align: center; color: rgb(0,0,0)">

- Version 0.2
+ Version 0.4.2.1

 </p>
 <hr />
 <p>
 </p>
 <hr />
 <p>


@@ -38,6 +38,7 @@
 </p>
 <p>
 Xournal can be downloaded at
 </p>
 <p>
 Xournal can be downloaded at

+<a href="http://xournal.sourceforge.net/">http://xournal.sourceforge.net/</a> or 

 <a href="http://math.mit.edu/~auroux/software/xournal/">http://math.mit.edu/~auroux/software/xournal/</a>
 </p>
 <p>
 <a href="http://math.mit.edu/~auroux/software/xournal/">http://math.mit.edu/~auroux/software/xournal/</a>
 </p>
 <p>


@@ -53,6 +54,7 @@ Xournal can be downloaded at
   <li> <a href="manual.html#tools">The drawing and selection tools</a> </li>
   <li> <a href="manual.html#pages-layers">Pages, layers, and backgrounds</a> </li>
   <li> <a href="manual.html#printing">Printing</a> </li>
   <li> <a href="manual.html#tools">The drawing and selection tools</a> </li>
   <li> <a href="manual.html#pages-layers">Pages, layers, and backgrounds</a> </li>
   <li> <a href="manual.html#printing">Printing</a> </li>

+  <li> <a href="manual.html#configuration">Configuration</a> </li>

   <li> <a href="manual.html#author">Author information, license, bug-reports</a> </li>
   <li> <a href="manual.html#changelog">Version history</a> </li>
   <li> <a href="manual.html#file-format">The file format</a> </li>
   <li> <a href="manual.html#author">Author information, license, bug-reports</a> </li>
   <li> <a href="manual.html#changelog">Version history</a> </li>
   <li> <a href="manual.html#file-format">The file format</a> </li>


@@ -93,12 +95,10 @@ the Pen Options submenu of the Tools menu).
 </p>
 <h3 class="subsub"><img src="pixmaps/eraser.png"> The eraser</h3>
 <p>
 </p>
 <h3 class="subsub"><img src="pixmaps/eraser.png"> The eraser</h3>
 <p>

-The eraser lets you erase what you have drawn. If your tablet's stylus
-has an eraser tip, and if the XInput extensions are enabled, the eraser
-will be automatically selected when drawing with the eraser tip.
-Another possibility is to enable the "Emulate Eraser" option in the Options
-menu, which lets you use button 2 or 3 on the stylus (mouse middle or right button)
-as an eraser.<br />
+The eraser lets you erase what you have drawn. 
+By default, stylus buttons 2 and 3 (mouse middle or right buttons) are
+mapped to the eraser tool.
+<br />

 The eraser comes in three different thicknesses (selected using the
 <a href="manual.html#thicknesses">thickness</a> toolbar buttons),
 and can operate in three different modes (Eraser Options submenu of
 The eraser comes in three different thicknesses (selected using the
 <a href="manual.html#thicknesses">thickness</a> toolbar buttons),
 and can operate in three different modes (Eraser Options submenu of


@@ -127,6 +127,28 @@ the Tools menu):
   is yellow) and thicknesses. Use the color and thickness toolbar buttons
   to change these settings.
 </p>
   is yellow) and thicknesses. Use the color and thickness toolbar buttons
   to change these settings.
 </p>

+<h3 class="subsub"><img src="pixmaps/text-tool.png"> The text tool</h3>
+<p>
+  To insert a new text item, click at the location where the text is to be
+  inserted on the page, then type it in or paste it using the contextual
+  menu (note: no wrapping is performed). To modify a text item, click inside
+  it. The font and point size can be modified using the "Text Font" command
+  in the Tools menu (or the toolbar button). The color is the same as that
+  currently selected for the pen (and can be modified using the toolbar
+  buttons).
+</p>
+<p>
+  Text items can contain arbitrary Unicode characters, provided that a
+  suitable font is installed on your system. However, languages written
+  in a direction other than left-to-right might not be handled properly.
+  If a journal contains some items in a font that is unavailable on your
+  system, another one will be substituted. (Also, text items will be
+  lost if the document is opened in a version of Xournal prior to 0.4).
+  Finally, note that the printing and PDF export features only accept
+  TrueType and Type 1 scalable fonts (do not use any bitmap fonts), and
+  that the typesetting of the text may be slightly different in the
+  printout.
+</p>

 <h3 class="subsub"><img src="pixmaps/ruler.png"> The ruler</h3>
 <p>
   The ruler is not a tool by itself, but rather a special operating mode
 <h3 class="subsub"><img src="pixmaps/ruler.png"> The ruler</h3>
 <p>
   The ruler is not a tool by itself, but rather a special operating mode


@@ -134,17 +156,44 @@ the Tools menu):
   line segments instead of curvy strokes. For simplicity, selecting the
   ruler when not in pen or highlighter mode automatically selects the pen.
 </p>
   line segments instead of curvy strokes. For simplicity, selecting the
   ruler when not in pen or highlighter mode automatically selects the pen.
 </p>

+<a name="recognizer"></a>
+<h3 class="subsub"><img src="pixmaps/shapes.png"> The shape recognizer</h3>
+<p>
+  The shape recognizer is also a special 
+  operating mode of the pen and highlighter tools. When it is enabled,
+  Xournal attempts to recognize geometric shapes as they are drawn, and
+  if successful will replace the drawn strokes accordingly. The shapes
+  that can be recognized are: line segments, circles, rectangles, arrows,
+  triangles and quadrilaterals. Polygonal shapes can be drawn in a single
+  stroke or in a sequence of consecutive strokes.
+</p>
+<p>
+  The recognizer is set to be as unobtrusive as possible, and should not
+  interfere too much with handwriting. (It differs in this and other ways
+  from another shape recognizer written for Xournal by Lukasz Kaiser).
+  As a result, it may only recognize shapes if you draw them carefully and
+  deliberately. Specific tips for better recognition: (1) for circles,
+  a closed curve that isn't quite round works better
+  than a rounder curve that doesn't close; (2) for arrows, it is better
+  to lift the pen before drawing the tip of the arrow, and make sure
+  the tip consists of two straight line segments;
+  (3) for very elongated rectangles,
+  recognition tends to be better if you lift the pen between consecutive
+  sides.
+</p>

 <h3 class="subsub"><img src="pixmaps/recycled.png"> Default tools</h3>
 <p>
 <h3 class="subsub"><img src="pixmaps/recycled.png"> Default tools</h3>
 <p>

-  Each drawing tool (pen, eraser, highlighter) has a default setting
-  (color, thickness, ...) associated to it.
-  The "Default Pen", "Default Eraser", and "Default Highlighter" entries of
+  Each tool (pen, eraser, highlighter, text) has a default setting
+  (color, thickness, ... for the drawing tools, font and size for the
+  text tool) associated to it.
+  The "Default Pen", "Default Eraser", "Default Highlighter", and
+  "Default Text" entries of

   the Tools menu select the appropriate tool and reset its settings to
   the defaults. The toolbar also includes a "Default" button which
   the Tools menu select the appropriate tool and reset its settings to
   the defaults. The toolbar also includes a "Default" button which

-  resets the currently selected drawing tool to its default settings,
+  resets the currently selected tool to its default settings,

   and a "Default Pen" button. <br />
   The "Set As Default" entry of the Tools menu takes the current settings
   and a "Default Pen" button. <br />
   The "Set As Default" entry of the Tools menu takes the current settings

-  of the currently selected drawing tool and makes them the new default.
+  of the currently selected tool and makes them the new default.

 </p>
 <a name="thicknesses"></a>
 <h3 class="subsub"><img src="pixmaps/thin.png"> <img src="pixmaps/medium.png">
 </p>
 <a name="thicknesses"></a>
 <h3 class="subsub"><img src="pixmaps/thin.png"> <img src="pixmaps/medium.png">


@@ -160,7 +209,9 @@ the Tools menu):
   All the strokes which are entirely contained within the rectangular region
   are selected.
   The selection can be moved within its page by clicking inside the
   All the strokes which are entirely contained within the rectangular region
   are selected.
   The selection can be moved within its page by clicking inside the

-  selection rectangle and dragging the cursor.
+  selection rectangle and dragging the cursor. If the cursor is dragged
+  to a different page, the selection will be moved to the topmost layer of
+  that page.

 </p>
 <p>
   The selection can be cut, duplicated, etc. (including to a different page
 </p>
 <p>
   The selection can be cut, duplicated, etc. (including to a different page


@@ -182,6 +233,19 @@ the Tools menu):
   space, or change the page height to an appropriate value (using the
   "Paper Size" entry in the Journal menu).
 </p>
   space, or change the page height to an appropriate value (using the
   "Paper Size" entry in the Journal menu).
 </p>

+<p>
+  If you drag the cursor below the bottom of the page (so that the
+  entire block being moved has become invisible), the items will be moved
+  to the next page (topmost layer); however, any items that were already
+  present on the next page are left unchanged. Similarly, dragging the
+  cursor above the top of the page so that the entire block being moved
+  becomes invisible results in the items being moved to the previous page.
+</p>
+<h3 class="subsub"><img src="pixmaps/hand.png"> Hand tool</h3>
+<p>
+  This tool lets you browse the journal; dragging the cursor scrolls the
+  view.
+</p>

 <h3 class="subsub">Undo and redo</h3>
 <p>
   All operations performed on the currently open journal (drawing, erasing,
 <h3 class="subsub">Undo and redo</h3>
 <p>
   All operations performed on the currently open journal (drawing, erasing,


@@ -190,6 +254,36 @@ the Tools menu):
   the corresponding entries in the Edit menu.<br />
   There is no limit to the depth of the undo/redo stack. It is cleared only
   when you quit the application or open a new journal.
   the corresponding entries in the Edit menu.<br />
   There is no limit to the depth of the undo/redo stack. It is cleared only
   when you quit the application or open a new journal.

+</p>
+<a name="mappings"></a>
+<h3 class="subsub">Button mappings</h3>
+<p>
+  Stylus buttons 2 and 3 (mouse middle and right buttons) can be mapped
+  to different tools using the appropriate submenus in the Options menu
+  (whereas the Tools menu and the toolbar buttons affect the primary tool
+  assigned to button 1). The default mapping is the eraser.
+</p>
+<p><b>Advanced configuration:</b>
+  if a secondary button is mapped to a drawing tool (pen, eraser, or
+  highlighter), the default is to "dynamically link" its settings to those
+  of the primary tool, which means that each drawing tool has common
+  settings (color, thickness, etc.) for all buttons.
+  Dynamic linking of brush settings
+  can be disabled by selecting the "Copy of current brush" option in the
+  "Button mapping" submenu. The settings of the tool for button 2 or 3 are
+  copied from the button 1 settings at the time when you select the option,
+  and afterwards they are no longer updated when the button 1 settings are
+  modified, thus making it possible to assign pens of different colors or
+  thicknesses to different buttons.
+</p>
+<p>
+  Another option that affects button mappings is the "Eraser tip" option.
+  If this option is turned on and the XInput extensions are enabled, then
+  the eraser tip of your tablet's stylus will automatically be remapped to
+  the eraser tool. This behavior, which overrides all other button mappings,
+  is most useful if your X server is configured to map the eraser tip of
+  your tablet's stylus to button 1.
+</p>

 <hr />
 <a name="pages-layers"></a>
 <h2 class="subtitle">Pages, layers, and backgrounds</h2>
 <hr />
 <a name="pages-layers"></a>
 <h2 class="subtitle">Pages, layers, and backgrounds</h2>


@@ -389,10 +483,10 @@ PDF files (for example <i>pdfmerge</i>).
 <h2 class="subtitle">Printing</h2>
 <p>
 Xournal uses the gnome-print architecture for printing. While it is very
 <h2 class="subtitle">Printing</h2>
 <p>
 Xournal uses the gnome-print architecture for printing. While it is very

-powerful, some aspects of the API leave to be desired,
-and future versions of Xournal will probably also include a native
-Postscript/PDF printing feature.
+powerful, some aspects of the API leave to be desired. As of version 0.3,
+Xournal also includes a native PDF printing feature.

 </p>
 </p>

+<h3 class="subsub">Printing via gnome-print</h3>

 <p>
 The "Printer" tab of the print dialog box lets you select a printer
 (either one of the printers installed on your system, or the generic
 <p>
 The "Printer" tab of the print dialog box lets you select a printer
 (either one of the printers installed on your system, or the generic


@@ -410,18 +504,59 @@ attempts to pre-fill the output file name (for the Postscript driver
 this often fails due to gnome-print API issues).
 </p>
 <p>
 this often fails due to gnome-print API issues).
 </p>
 <p>

-The "Print to PDF" entry of the File menu directly generates a PDF file
-using the PDF virtual printer, without bringing up the dialog box
-(the page size is the default one for that printer, usually A4). 

 Note that the PDF virtual printer produces files that are very large
 Note that the PDF virtual printer produces files that are very large

-and far from optimal, so in the current state of things it is better
-to generate a Postscript file and use a converter such as ps2pdf.
-</p>
-<p>
+and far from optimal, so its use is not recommended.

 The gnome-print architecture also forces page backgrounds (bitmaps
 and PDF) to be generated as uncompressed bitmaps, which leads to gigantic
 The gnome-print architecture also forces page backgrounds (bitmaps
 and PDF) to be generated as uncompressed bitmaps, which leads to gigantic

-print job files. An alternative to gnome-print will be
-implemented in a future release of Xournal.
+print job files. A better alternative is to export a PDF file, and
+print the PDF file.
+</p>
+<h3 class="subsub">Exporting to PDF</h3>
+<p>
+Starting with version 0.3, Xournal provides its own PDF rendering
+engine. The "Export to PDF" command (in the File menu) produces a
+PDF-1.4 file from the currently loaded document. The resulting PDF
+file is much more compact than those produced via gnome-print, and
+its pages have the same size as in Xournal. Highlighter strokes
+are rendered in a partially transparent manner (note however that
+applications such as xpdf and ghostview do not always handle
+PDF transparency properly). Text items are rendered by embedding
+TrueType subsets or Type 1 fonts into the PDF document as appropriate.
+</p>
+<p>
+Xournal also includes a PDF file parser compatible with PDF format
+version 1.4; the compression features of PDF 1.5 (Acrobat 6) are
+not supported. When exporting a document that uses PDF
+backgrounds, Xournal attempts to preserve most of the structure of
+the original PDF file (however, auxiliary data such as thumbnails, hyperlinks,
+and annotations are lost). If Xournal is unable to parse the PDF
+file, the backgrounds are converted to (compressed) bitmaps and a new
+PDF file is generated from scratch.
+</p>
+<hr />
+<a name="configuration"></a>
+<h2 class="subtitle">Configuration</h2>
+<p>
+Starting with version 0.3.2, Xournal's configuration settings can be
+saved to a file (<tt>~user/.xournal/config</tt>) by using the "Save
+Preferences" command in the Options menu. The settings saved in the
+configuration file include in particular:
+<ul>
+<li>general display preferences: zoom level, window size, ...</li>
+<li>default paper settings (as set by the "Set As Default" command in
+the Journal menu)</li>
+<li>default settings for the pen, eraser, highlighter, and text tools
+(as set by the "Set As Default" command in the Tools menu)</li>
+<li>mappings for buttons 2 and 3</li>
+<li>the various preferences set in the Options menu</li>
+</ul>
+The configuration file also gives access to additional customization
+options which cannot be set from the user interface, such as: the
+display resolution in pixels per inch, the step increment in zoom factors,
+the tool selected at startup, the thickness of the various drawing tools,
+the default directory for opening and saving files, the visibility and
+position of the menu and toolbars, ...
+</p>

 <hr />
 <a name="author"></a>
 <h2 class="subtitle">Author information, license, bug-reports</h2>
 <hr />
 <a name="author"></a>
 <h2 class="subtitle">Author information, license, bug-reports</h2>


@@ -432,23 +567,137 @@ Xournal is written by Denis Auroux
 </p>
 <p>Feel free to contact me with bug reports and suggestions; I apologize
 in advance if I am unable to respond properly to some requests.
 </p>
 <p>Feel free to contact me with bug reports and suggestions; I apologize
 in advance if I am unable to respond properly to some requests.

-List of known bugs/misfeatures (no need to report them again):
-<ul>
- <li> highlighter strokes become opaque on printouts (apparently a bug in
-      libgnomeprint).</li>
- <li> print settings are not saved from one print command to the next.</li>
- <li> printing to PDF and/or printing page backgrounds generates large files.</li>
- <li> preferences are not saved on disk.</li>
- <li> selection cannot be dragged across page boundaries.</li>
-</ul>
+</p><p>

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

+<p>
+Bug reports and suggestions can also be submitted on Xournal's
+<a href="http://www.sourceforge.net/projects/xournal/">SourceForge page.</a>
+</p>

 <hr />
 <a name="changelog"></a>
 <h2 class="subtitle">Version history</h2>
 <p>
 <hr />
 <a name="changelog"></a>
 <h2 class="subtitle">Version history</h2>
 <p>

+Version 0.4.2.1 (Mar 27, 2008):
+<ul>
+ <li>bugfix for #1926757 (crash upon pasting variable-width stroke)</li>
+ <li>bugfix: set ruler/recognizer setting to default upon switching tools</li>
+</ul>
+</p>
+<p>
+Version 0.4.2 (Mar 25, 2008):
+<ul>
+ <li>bugfixes for X.org 7.3; allow XInput and core events in reverse order</li>
+ <li>resize selection (patch contributed by Andy Neitzke)</li>
+ <li>pressure sensitive pen (variable stroke width) (patch by Andy Neitzke)</li>
+ <li>geometric shape recognizer (after an idea by Lukasz Kaiser) 
+     (see <a href="manual.html#recognizer">here</a>)</li>
+ <li>clean up compiler warnings (patch contributed by Danny Kukawka)</li>
+</ul>
+</p>
+<p>
+Version 0.4.1 (Sep 15, 2007):
+<ul>
+ <li> bugfix: compatibility with new versions of pdftoppm (thanks to
+      Vincenzo Ciancia)</li>
+ <li>GTK+ 2.11 event processing bugfix</li>
+ <li>minor bugfixes: hand tool, handling of filenames containing '&amp;'</li>
+ <li>desktop and MIME files (thanks to Mathieu Bouchard) + updated installer</li>
+ <li>config options: left-handed scrollbar (contributed by Uwe Winter),
+     hide some menu items (customizable in config file), auto-save
+     preferences</li>
+</ul>
+</p>
+<p>
+Version 0.4.0.1 (September 3, 2007):
+<ul>
+ <li>bugfixes for GTK+ 2.11 behavior (thanks to everyone who reported bugs)</li>
+</ul>
+</p>
+<p>
+Version 0.4 (August 15, 2007):
+<ul>
+ <li>text tool (handles most TrueType and Type1 fonts)</li>
+ <li>font selection dialog and button</li>
+ <li>keyboard mappings (arrow keys)</li>
+ <li>menu mnemonics and shortcuts (suggestions by Jean-Baptiste Rouquier)</li>
+ <li>more responsive hand tool</li>
+ <li>bugfix for GTK+ 2.11 XInput behavior (thanks to Robert Gerlach)</li>
+ <li>various minor bugfixes and enhancements</li>
+</ul>
+</p>
+<p>
+Version 0.3.3 (January 31, 2007):
+<ul>
+ <li>bugfix: upon loading a new file, zoom is set to default startup zoom</li>
+ <li>config option to allow input from a mouse or other core pointer device</li>
+ <li>config file entry to specify a default location for open/save
+     (patch contributed by Andy Neitzke)</li>
+ <li>config file entries to customize visibility and position of toolbars</li>
+ <li>icon (thanks to Michele Codutti)</li>
+</ul>
+</p>
+<p>
+Version 0.3.2 (November 25, 2006):
+<ul>
+ <li>preferences file and Save Preferences command</li>
+ <li>extra customization (via preferences file)</li>
+ <li>minor UI changes (patch contributed by Eduardo de Barros Lima)</li>
+ <li>hand tool (partially contributed by Vincenzo Ciancia)</li>
+ <li>a few bugfixes in rendering of bitmap backgrounds</li>
+</ul>
+<p>
+Version 0.3.1 (August 3, 2006):
+<ul>
+ <li>fixed a file format bug on systems with non-standard numeric locale
+     (bug reported by Gert Renckens)</li>
+</ul>
+</p>
+<p>
+Version 0.3 (July 23, 2006):
+<ul>
+ <li>new PDF rendering engine: export to PDF generates optimized files
+   (smaller and more accurate)</li>
+ <li>export to PDF handles PDF backgrounds (up to PDF-1.4) natively
+    (without conversion to bitmap)</li>
+ <li>default thickness of erasers and highlighters slightly increased</li>
+ <li>zoom dialog box with input box and "fit to page height" option</li>
+ <li>file format documentation added to the user's manual</li>
+</ul>
+</p>
+<p>
+Version 0.2.2 (June 5, 2006):
+<ul>
+ <li>mapping of tools to stylus buttons (the options menu has new entries
+    to allow the mapping of buttons 2 and 3 to arbitrary tools; the tools
+    menu and toolbar affect the settings for button 1)
+    (see <a href="manual.html#mappings">here</a>)</li>
+ <li>moving selection by drag-and-drop works across page boundaries</li>
+ <li>vertical space tool can move items to next page (only when the entire
+    block being moved has crossed the page boundary; items on the new page
+    are not moved)</li>
+ <li>"apply to all pages" is now a toggle button affecting the behavior of
+    paper size, color, and style commands</li>
+ <li>change in the behavior of the selection upon switching between tools</li>
+</ul>
+</p>
+<p>
+Version 0.2.1 (June 3, 2006):
+<ul>
+ <li>recently used files listed in file menu</li>
+ <li>can change color or thickness of pen strokes in selection</li>
+ <li>function to apply paper style to all pages</li>
+ <li>can specify on command line a PDF file to annotate</li>
+ <li>suggest a derived file name for PDF annotation</li>
+ <li>speed up switching between pages</li>
+ <li>fixed a bug in XInput initialization (thanks to Luca de Cicco)</li>
+ <li>fixed a bug in print ranges (thanks to Mathieu Bouchard)</li>
+ <li>fixed a refresh bug in rescaling bitmap backgrounds</li>
+</ul>
+</p>
+<p>

 Version 0.2 (January 29, 2006):
 <ul>
  <li>PDF file annotation using xpdf's pdftoppm
 Version 0.2 (January 29, 2006):
 <ul>
  <li>PDF file annotation using xpdf's pdftoppm


@@ -470,23 +719,171 @@ Version 0.1.1 (January 5, 2006):
 <p>
 Version 0.1 (January 2, 2006): initial release.
 </p>
 <p>
 Version 0.1 (January 2, 2006): initial release.
 </p>

+<hr />
+<a name="file-format"></a>
+<h2 class="subtitle">The file format</h2>
+<h3 class="subsub">Overall structure</h3>
+<p>
+Xournal stores its data in gzipped XML-like files. The gzipped data consists
+of a succession of XML tags describing the document. By convention, the
+file header and trailer look like this:
+<pre>
+&lt;?xml version="1.0" standalone="no"?&gt;
+&lt;xournal version="..."&gt;
+&lt;title&gt;Xournal document - see http://math.mit.edu/~auroux/software/xournal/&lt;/title&gt;
+... sequence of pages ...
+&lt;/xournal&gt;
+</pre>
+The &lt;title&gt; and &lt;xournal&gt; tags may only appear within the file
+header (not within the pages of the document). The <i>version</i> attribute of
+the &lt;xournal&gt; tag indicates which version of Xournal was used to
+create the document; it is currently ignored, but may be used in a later
+release if the file format changes in an incompatible manner.
+(Following a suggestion of Matteo Abrate, starting with version 0.4 the
+&lt;xournal&gt; tag is the document's root tag, and encloses all other tags).
+</p>
+<p>
+The rest of the file is a sequence of pages, specified by a
+&lt;page&gt; tag, whose attributes <i>width</i> and <i>height</i> specify the
+physical size of the page in points (1/72 in). The width and height
+parameters are floating point values. The format of a page is therefore:
+<pre>
+&lt;page width="..." height="..."&gt;
+... page contents ...
+&lt;/page&gt;
+</pre>
+</p>
+<h3 class="subsub">Page background</h3>

 <p>
 <p>

-Features yet to be implemented:
+The first entry within a page describes the page background.
+It consists of a &lt;background&gt; tag followed by several mandatory
+XML attributes. The first attribute is always <i>type</i>, which
+can take three possible values: "solid" for a solid background, "pixmap"
+for a bitmap background, and "pdf" if the background is a page of a PDF
+document. The rest of the attributes depends on the type of background.

 <ul>
 <ul>

- <li>freeform selection tool</li>
- <li>preferences file; persistent printer settings; recent files list</li>
- <li>native PDF print feature</li>
- <li>various functionalities (flatten layers, drag-and-drop across pages, ...)</li>
+<li><p> Solid background: <tt>&lt;background type="solid" color="..."
+style="..." /&gt;</tt> <br />The <i>color</i> attribute takes one of
+the standard values "white", "yellow", "pink", "orange", "blue", "green",
+or can specify a hexadecimal RGBA value in the format "#rrggbbaa". The
+<i>style</i> attribute takes one of the standard values "plain", "lined",
+"ruled", or "graph".</p>
+</li>
+<li><p> Bitmap background: <tt>&lt;background type="pixmap" domain="..."
+filename="..." /&gt;</tt> <br />
+The <i>domain</i> attribute takes one of the standard values "absolute",
+"attach", or "clone". A value of "absolute" indicates that the bitmap is
+found in the file specified by <i>filename</i>. The bitmap can be in any
+format recognized by the gdk-pixbuf library; this includes most of the
+common bitmap formats (JPEG, PNG, BMP, GIF, PCX, PNM, TIFF, ...).
+<br />A value
+of "attach" indicates that the bitmap is an attachment to the Xournal file.
+The bitmap is in PNG format, and resides in a file whose name is derived
+from that of the main Xournal file by appending to it a dot and the contents
+of the <i>filename</i> attribute. For example, if the Xournal file is in
+<tt>file.xoj</tt> and the <i>filename</i> attribute is <tt>"bg_1.png"</tt>
+then the bitmap file is <tt>file.xoj.bg_1.png</tt> (Xournal saves attached
+bitmaps sequentially in files ...bg_1.png, ...bg_2.png, etc.)
+<br />A value of "clone" indicates that the bitmap is identical to the
+background of a previous page of the journal; the <i>filename</i> attribute
+then specifies the page number, starting with 0 for the first page. For
+example, if a <i>filename</i> value of <tt>"1"</tt> indicates that the
+background bitmap is identical to that of the second page.
+</p>
+</li>
+<li><p> PDF background: <tt>&lt;background type="pdf" domain="..."
+filename="..." pageno="..." /&gt;</tt> or
+<tt>&lt;background type="pdf" pageno="..." /&gt;</tt>
+<br />The <i>domain</i> and <i>filename</i> attributes must be specified
+for the first page of the journal that uses a PDF background, and must
+be omitted subsequently for every other page that uses a PDF background.
+The <i>domain</i> attribute takes one of the standard values
+"absolute" and "attach"; the PDF document is to be found in the file
+specified by <i>filename</i> (if <i>domain</i> is "absolute"), or in the
+file whose name is obtained by appending a dot and the contents of the
+<i>filename</i> attribute to the name of the main Xournal file (if
+<i>domain</i> is "attach"). The <i>pageno</i> attribute specifies which
+page of the PDF file is used as background, starting with 1 for the first
+page of the PDF file.
+</p>
+</li>

 </ul>
 </p>
 </ul>
 </p>

-<hr />
-<a name="file-format"></a>
-<h2 class="subtitle">The file format</h2>
+<h3 class="subsub">Layers and strokes</h3>

 <p>
 <p>

-XOJ files are gzipped XML-like files. A more precise documentation of
-the file format will be added at a later date. Meanwhile, most of the
-format should be easy to figure out by trial-and-error or by looking
-at the source; if some details are unclear, feel free to ask.
+After the line specifying the background, the remainder of a &lt;page&gt;
+section is occupied by one or more layer sections
+<pre>&lt;layer&gt; ... &lt;/layer&gt;</pre>
+describing the various items within a layer. Every page must
+contain at least one layer; a layer may be empty. The successive layers
+are listed in their stacking order, from bottom to top.
+</p>
+<p>
+A layer consists of a collection of items, listed in the order in which
+they should be drawn
+(from bottom-most to top-most).
+Up to version 0.3.3, the only legal contents within a layer are 
+strokes. The format of a stroke is:
+<pre>&lt;stroke tool="..." color="..." width="..."&gt;
+... list of coordinates ...
+&lt;/stroke&gt;
+</pre>
+The <i>tool</i> attribute can take the values "pen", "highlighter", or
+"eraser" depending on the tool used to create the stroke (pen, highlighter,
+or whiteout eraser); a value of "highlighter" indicates that the stroke
+should be painted in a partially transparent manner (Xournal uses an alpha
+coefficient of 0.5).
+</p>
+<p>
+The <i>color</i> attribute can take one of the standard values "black",
+"blue", "red", "green", "gray", "lightblue", "lightgreen", "magenta",
+"orange", "yellow", "white", or can specify a hexadecimal RGBA value in
+the format "#rrggbbaa". 
+</p>
+<p>
+The <i>width</i> attribute is a floating-point
+number (or a sequence of floating-point numbers starting with version 0.4.2),
+and specifies the width of the stroke in points (1/72 in). (For a
+variable-width stroke, the <i>width</i> attribute contains a
+whitespace-separated succession of floating-point values: first the
+nominal brush width, and then the width of each successive segment forming
+the stroke.)
+</p>
+<p>
+The list of coordinates is simply a succession of floating-point values,
+separated by whitespace.
+The number of given values must be even; consecutive pairs of values give
+the <i>x</i> and <i>y</i> coordinates of each point along the stroke.
+These values are expressed in points (1/72 in). The coordinates (0,0)
+represent the top-left corner of the page: hence x is measured from the left
+of the page, and y is measured from the top of the page.
+</p>
+<p>
+Every stroke must contain at least two points (four floating point values).
+Moreover, two consecutive points on the stroke should be spaced no more
+than 5 units apart or so; longer line segments should be subdivided as
+appropriate (otherwise the eraser tool will not interact properly with the
+stroke). The default precision used by Xournal for the x,y coordinates is
+0.01 unit (1/7200 in).
+</p>
+<p>Starting with version 0.4, layers also contain text items.
+The format of a text item is:
+<pre>&lt;text font="..." size="..." x="..." y="..." color="..."&gt;... text ...&lt;/text&gt;
+</pre>
+The <i>font</i> attribute contains the font name, for example "Serif Bold
+Italic"; if the font is not available, another font will be substituted.
+The <i>size</i> attribute specifies the font size in points. The <i>x</i>
+and <i>y</i> attributes specify the coordinates of the top-left corner
+of the text box in page coordinates (measured in points from the top-left
+corner of the page). Finally, the <i>color</i> attribute contains either
+the name of a standard color or a hexadecimal RGBA value (see above).
+</p>
+<p>
+The contents of the text are encoded in UTF-8, with the characters
+<tt>'&amp;', '&lt;', '&gt;'</tt> replaced by <tt>&amp;amp;, &amp;lt;,
+&amp;gt;</tt>. Whitespace and linefeeds are preserved (in particular,
+no extraneous whitespace should be inserted between the enclosing tags
+and the text itself).

 </p>
 <hr />
 <a name="installation"></a>
 </p>
 <hr />
 <a name="installation"></a>


@@ -498,7 +895,7 @@ modern Linux distributions such as Fedora Core 3 or later, or RHEL 4 or
 later):
 <ul>
  <li> the <b>gtk+</b> libraries, version <b>2.4</b> or later 
 later):
 <ul>
  <li> the <b>gtk+</b> libraries, version <b>2.4</b> or later 

-       (2.6 recommended) &nbsp; (package gtk2 and dependencies)</li>
+       (<b>2.6</b> strongly recommended) &nbsp; (package gtk2 and dependencies)</li>

  <li> <b>libgnomecanvas</b> version <b>2.4</b> or later &nbsp;
        (package libgnomecanvas and dependencies)</li>
  <li> <b>libgnomeprint</b> and <b>libgnomeprintui</b> version <b>2.2</b> or later &nbsp;
  <li> <b>libgnomecanvas</b> version <b>2.4</b> or later &nbsp;
        (package libgnomecanvas and dependencies)</li>
  <li> <b>libgnomeprint</b> and <b>libgnomeprintui</b> version <b>2.2</b> or later &nbsp;


@@ -540,6 +937,7 @@ installed on your system).
 ./autogen.sh
 make
 (as root) make install
 ./autogen.sh
 make
 (as root) make install

+(as root) make desktop-install

 </pre>
 </p>
 <p>
 </pre>
 </p>
 <p>


@@ -549,6 +947,7 @@ make
 ./configure --prefix=$HOME
 make
 make install
 ./configure --prefix=$HOME
 make
 make install

+make home-desktop-install

 </pre>
 </p>
 <p><b>Configure error message:</b> <br />
 </pre>
 </p>
 <p><b>Configure error message:</b> <br />


@@ -631,6 +1030,20 @@ installation instructions specific to your model: for example, the
 use USB instead; the BottomX and BottomY values correspond to the physical
 resolution of the tablet and will vary from one model to another.
 </p>
 use USB instead; the BottomX and BottomY values correspond to the physical
 resolution of the tablet and will vary from one model to another.
 </p>

+<p>
+For historical reasons, most X servers do not allow the input device
+designated as the "core pointer" in the X server's configuration file
+to be used as an XInput extension device. Thus, your tablet input devices
+should <b>not</b> be designated as the core pointer device. Instead, they
+should be configured with the "SendCoreEvents" option, which enables them
+to simultaneously generate XInput extension events and move the cursor on
+the screen. Since high-resolution coordinates cannot be obtained for the
+core pointer device, it is disabled in Xournal by default. 
+Starting with version 0.3.3,
+it is possible to have core events processed alongside with extension
+events (uncheck "Discard Core Events" in the Options menu); however, in
+some rare cases this may lead to a loss of resolution on all devices.
+</p>

 <h3 class="subsub">The cursor doesn't appear in the right place...</h3>
 <p>
 If the mouse pointer does not follow accurately the position of the stylus,
 <h3 class="subsub">The cursor doesn't appear in the right place...</h3>
 <p>
 If the mouse pointer does not follow accurately the position of the stylus,


@@ -656,9 +1069,9 @@ linuxwacom driver, the tablet calibration information is often not updated
 properly when using xsetwacom).
 </p>
 <p>
 properly when using xsetwacom).
 </p>
 <p>

-<b>Important:</b> due to issues with the linuxwacom driver, it is important
-to either upgrade your driver to a <a href="manual.html#wacompatch">patched
-version</a>, or restrict your choice of settings as follows:
+<b>Important:</b> due to issues with old versions of the linuxwacom
+driver (&lt; 0.7.6), it is important to upgrade your driver,
+or restrict your choice of settings as follows:

 <ul>
 <li> your calibration settings should not be changed at runtime (i.e.,
 insert your settings directly into your X server configuration file.
 <ul>
 <li> your calibration settings should not be changed at runtime (i.e.,
 insert your settings directly into your X server configuration file.


@@ -670,36 +1083,37 @@ Do not add a list of xsetwacom commands to your startup files).
 </p>
 <h3 class="subsub">Strokes aren't drawn under the cursor...</h3>
 <p>
 </p>
 <h3 class="subsub">Strokes aren't drawn under the cursor...</h3>
 <p>

-This is due to misfeatures in the linuxwacom driver. Typically, this
-will happen in all of the following cases:
+This is typically due to misfeatures in the linuxwacom driver in versions
+prior to 0.7.6, and will happen in all of the following cases:

 <ul>
 <li> the calibration settings have been changed after the X server was
 started (using xsetwacom) </li>
 <li> the calibration TopX or TopY values are not 0 </li>
 <li> the display has been rotated </li>
 </ul>
 <ul>
 <li> the calibration settings have been changed after the X server was
 started (using xsetwacom) </li>
 <li> the calibration TopX or TopY values are not 0 </li>
 <li> the display has been rotated </li>
 </ul>

-Future versions of the driver may fix these issues. Meanwhile, you can
+Most of these issues should have been fixed in version 0.7.6 of the
+wacom driver. Otherwise, you can

 either disable XInput support in Xournal (in the Options menu), at a
 price of a severe loss of resolution (and the eraser tip won't be detected
 either disable XInput support in Xournal (in the Options menu), at a
 price of a severe loss of resolution (and the eraser tip won't be detected

-anymore), or apply this <a href="manual.html#wacompatch">patch</a>
-to the wacom driver.
+anymore), or inspect carefully your X server configuration and make
+sure the tablet devices are calibrated and configured properly.

 </p>
 <p>
 I have also had a report that one of the workarounds used by Xournal to
 bypass a calibration bug in GTK+ can actually entirely prevent strokes
 from being drawn. If you are being unsuccessful at drawing in Xournal
 </p>
 <p>
 I have also had a report that one of the workarounds used by Xournal to
 bypass a calibration bug in GTK+ can actually entirely prevent strokes
 from being drawn. If you are being unsuccessful at drawing in Xournal

-with XInput enabled, try recompiling after changing the first line of
-<tt>src/main.c</tt> to
-<pre>#define ENABLE_XINPUT_BUGFIX 0</pre>
+with XInput enabled, try recompiling after commenting out the line
+<pre>#define ENABLE_XINPUT_BUGFIX</pre>
+near the beginning of <tt>src/xournal.h</tt>.

 If this modification does improve things for you, and if you have a bit
 of spare time to help investigate the causes of this problem, please
 contact me.
 </p>
 <h3 class="subsub">On-the-fly display rotation</h3>
 <p> 
 If this modification does improve things for you, and if you have a bit
 of spare time to help investigate the causes of this problem, please
 contact me.
 </p>
 <h3 class="subsub">On-the-fly display rotation</h3>
 <p> 

-You need an X server that supports the RANDR extension, and a
-<a href="manual.html#wacompatch">patched</a> version of the linuxwacom
-driver to support on-the-fly rotation.
+You need an X server that supports the RANDR extension, and a sufficiently
+recent (0.7.6 or later) 
+version of the linuxwacom driver to support on-the-fly rotation.

 </p>
 <p>
 To set the tablet in portrait mode:
 </p>
 <p>
 To set the tablet in portrait mode:


@@ -717,18 +1131,5 @@ otherwise the tablet calibration in Xournal may (and most likely will)
 become incorrect.
 Exit Xournal and restart it after the display has been rotated.
 </p>
 become incorrect.
 Exit Xournal and restart it after the display has been rotated.
 </p>

-<a name="wacompatch"></a>
-<h3 class="subsub">Linuxwacom patch for calibration and rotation</h3>
-<p>
-This patch fixes rotation and calibration issues with the linuxwacom driver
-version 0.7.0.
-<ul>
-<li>The <a href="http://math.mit.edu/~auroux/software/xournal/linuxwacom-0.7.0-rotate-patch">patch
-file</a> for the linuxwacom source code (also included with the Xournal
-distribution).</li>
-<li>The <a href="http://math.mit.edu/~auroux/software/xournal/linuxwacom-rotate-patch.tar.gz">patched
-binaries</a> for the X.org X server.</li>
-</ul>
-</p>

 </body>
 </html>
 </body>
 </html>