### Meta-Information

1. Q: What version of the FAQ is this?
A: This is version 1.13, modified 28 Mar 2006.

2. Q: Who maintains this FAQ?
A: Lars Clausen <lrclause@cs.uiuc.edu> is the main maintainer, but anyone with write access to the www.gnome.org SVN project can update it.

3. Q: Where can I find the newest version of this FAQ?

4. Q: Who made this FAQ?
A: This FAQ was put together by Lars Clausen <lrclause@cs.uiuc.edu>. Most of the material came out of the Dia mailing list. The following people contributed more advice: Kerry <needles@industrialmusic.com>, James Henstridge <james@daa.com.au>, Simon Josefsson <simon@josefsson.org>, Jacek Pliszka <Jacek.Pliszka@fuw.edu.pl>, Steffen Macke <sdteffen@yahoo.com>, Robert Campbell <rob.campbell@visto.com>>, and Hubert Figuiere <hfiguiere@teaser.fr>.

5. Q: What's new in this version of the FAQ?
A: Updated for version 0.94, with explanations of problems in rotation, autorouting, and X-less conversion.

### The Dia interface

1. Q: How can I do anything but creating and moving objects?
A: Like The Gimp, Dia depends heavily on a menu on the right mouse button inside the diagram. That menu contains all the diagram-specific actions and a few other things, so you almost never have to find the menu on the toolbox. A snapshot shows an example of the menu.

2. Q: I try to change diagram properties, but nothing happens.
A: The preferences dialog only affects diagrams that are created thereafter. To change grid lines etc., go to the View menu and select settings there. The settings will be saved with the diagram.

3. Q: I don't have a middle mouse button, what can I do?
A: Unix (XFree86): If EmulateThirdButton is enabled (which it should be if you have a two-button mouse), you can make a middle-button click by pressing both buttons simultaneously (an action also known as chording). Windows: If you don't have a middle mouse button, hold down the Ctrl key and use the right mouse button.

4. Q: How can I set or change an accelerator key for a function in the menu?
A: Highlight the menu item then press the desired key or key-combination. To remove an assigned accelerator key, highlight the menu item then press the delete key. If you wish to reassign an accelerator key, it is not necessary to delete the current assignment first. Simply highlight the new menu item and press the key or key-combination. Notice that as of 0.91 (GTK-2.0), Delete can also be assigned, if no other key is assigned to that menu item.

5. Q: How can I set or change an accelerator key for one of the icons in the main window?
A: These functions correspond to the items in the Tools menu. Set or change their accelerator keys there.

6. Q: What are the five radio-buttons in the Select menu for?
A: They determine what happens when you drag-select objects. Normally, only the objects included in the drag area end up selected. By selecting other choices in the Select radio menu, you can change that behavior:
Union:
Both the drag-selected objects and the previously selected objects end up selected.
Intersect:
The only objects that end up selected are those that were already selected and were drag-selected.
Remove:
Those previously selected objects that are in the drag area become unselected.
Invert:
The objects in the drag area change selectedness: Unselected objects become selected, selected objects become unselected. The objects outside the drag area are not affected.
These operations correspond to set operations between the previously selected objects and the drag-selected objects.

### Making diagrams with Dia

1. Q: How do I add bends to a zig-zag line?
A: The middle mouse button gives an object-specific menu. For zig-zag lines, poly lines and bezier lines, that menu allows you to add and remove bends.

2. Q: How do I make a zig-zag line go horizontally?
A: As of version 0.93, zig-zag lines support a primitive form of autorouting that is intended to solve this problem and make it easier to make the diagrams look good. The autorouting algorithm does not attempt to avoid objects, but should at least make the lines go the right direction out from connection points. If it doesn't appear to work, double-click the zig-zag line and check that autorouting is on for it. This setting can also be accessed from the object menu.

For previous versions, here is a workaround for how to make zigzags change direction:

Using the object-specific menu on the middle mouse button, create an extra segment at each end of the line, then delete the middle segment:

3. Q: Why can't I resize classes etc.?
A: The size of classes is decided by their contents, especially the text. Note that you can scale the entire diagram when you print, see the question about page fitting.

4. Q: Why do elements have a fixed number of connection points?
A: We've been thinking about how to allow more connection points. Point is, there are several different ways it could be done that all make sense, and we'd like to get the most usable of them, while maintaining backwards compatibility. Note that the standard Line object allows you to add more connection points to it by the middle mouse menu. You can in a pinch place a line along the edge of an object and use the lines connection points:)

5. Q: Why can't Dia rotate arbitrarily?
A: Neither X nor GTK has built-in support for rotating arbitrary shapes (text, ellipses etc). Work is being done on a Display Postscript interface that will allow arbitrary rotation. Work is also in progress on FreeType support, which would allow for rotation.

Having rotated text is only part of the problem. We also need infrastructure so that handles, connection points, bounding boxes etc are rotated along with the object. Help on this would be appreciated.

6. Q: Why can't I add more connection points to objects?
A: You can, for some objects. Adding connection points in general is a tricky problem, as it is difficult to make sure that the points keep their placement after a reload. The standard line object allows adding more points via the object menu.

7. Q: Why don't the fonts work right?
A: Font support is not very standard in X, especially when you want to make images, print, and send the files to other people. In Dia version 0.90 and earlier, you can improve things by installing the urw-aliases package (or the GhostScript fonts). After installing the package, you will need to do a simple edit of a config file. Edit /etc/X11/fs/config and move the line /usr/share/fonts/default/urw-aliases to just below the ...:unscaled lines (make sure the commas are in the correct places after making the change). Then run killall -USR1 xfs to get the font server to reread its config file. The URW fonts should be used in place of the adobe ones they are clones of when an unscaled bitmap version can't be found.

As of 0.91, Dia on Unix uses the FreeType library to provide better font support. The fonts for this are in turn controlled by font-config. Note that this means that remote fonts servers cannot be used.

8. Q: The fonts are really unreadably tiny, either on screen or when writing PNG.
A: Dia 0.91 assumed things about Pango that weren't guaranteed, but didn't make a difference at the time. However, Pango 1.2.4 and up changed so that Dia's wrong assumptions now cause problems. This is fixed in Dia 0.92.1. Alternatively, if you can't install 0.92.1, you can downgrade your Pango to below 1.2.4. We highly recommend using the newest version of Dia, though. In Dia 0.92-0.94, we used a reworked cache which still didn't quite keep different sizes of the same text apart, so text would change size between huge, tiny and normal. In 0.95, the cache is disabled.

### Saving and Printing

1. Q: What format is the .dia file?
A: The native Dia file format (extension .dia) is XML compressed with GZip. You can select not to compress the files in the Preferences or in the save dialog.

2. Q: How can I scale the diagram to fit a page?
A: In the Page Setup dialog (selected from File/Page Setup), select Fit to:, and the blue lines will continuously self-adjust to fit to a page (or several pages).

3. Q: How do I use a exported TeX/PSTricks file in my TeX document?
A: First add \usepackage{pstricks} to the preamble of your TeX document. Then include your image as
\begin{figure}
\centering
\input{filename.tex}
\caption{A caption}
\label{figure:alabel}
\end{figure}


Note: Up to and including version 0.86, Dia doesn't deal correctly with some functions that PSTricks doesn't implement. You may have to change the start of the generated file to look like this: Then uncomment the three commands in the generated TeX file (unless you have a PSTricks with this functionality implemented), so it looks like:

% PSTricks TeX macro
% Title: x500name.dia
% Creator: Dia v0.86
% CreationDate: Thu Oct  5 11:25:54 2000
% For: a user
% \usepackage{pstricks}
\providecommand{\setlinejoinmode}[1]{}
\providecommand{\setlinecaps}[1]{}
\providecommand{\setfont}[2]{}
...


Note: PSTricks in the tetex-1.0.6-11 RPM (used in Red Hat Linux 6.2) is buggy. Easiest fix is to get pstricks.tex from CTAN and put it in /usr/share/texmf/tex/generic/pstricks/.

4. Q: I wish I had nice zigzags and coils as in PSTricks. How could I get them?
A: Draw them as standard lines in dia. Then in the .tex  file replace \psline by \pccoil or \pczigzag. For more information on their arguments look into your PSTricks documentation included in your PSTricks package or at PSTricks home page. Careful! Lines with more then one segment have to be split into separate segments when pccoil and pczigzag are used.

5. Q: How do I put (La)TeX formulas on my diagram?
A: Put them as you would put them in TeX, e.g.:  $\delta^{\dagger}_2$. At the moment of writing this FAQ it is not yet displayed correctly in dia but TeX code produced should be fine. The bounding-box of the formula will not be calculated correctly.

6. Q: Why is printing broken?
A: Dia has several ways to print: Dia print, Gnome print and Export as Postscript. A given compilation of Dia uses either Dia print or Gnome print. Dia's support for Gnome print is currently buggy and disabled by default, but some distributions (Red Hat for one) compile it in anyway. If you have such a version of Dia installed, you can Export as Postscript instead of printing, and then print the resulting file.

7. Q: How can I use Dia to convert files without running X?
A: Version 0.94 of Dia should be able to convert files without running X. However, a working installation of GTK is required to link the program, and Pango must be available for text conversion.

Earlier versions of Dia depend on X for various things, but it is planned to allow conversions without running X. In the meanwhile, you can use Xvbf to simulate an X server with the command:

startx "/usr/bin/env DISPLAY=:1 /usr/bin/dia -e $HOME/tmp/foo.png$HOME/tmp/foo.dia" -- /usr/X11R6/bin/Xvfb :1 -once -nolisten tcp

Thanks to Basile Starynkevitch for this hint.

8. Q: How do I make Dia use PostScript fonts instead of Pango rendering?
A: The current PostScript output on systems with font-config involves rendering the fonts as bezier curves. This gives an (almost) perfect output, but doesn't allow PostScript tools to operate on the fonts. If you want to get output using PostScript fonts, use the EPS export filter marked as "using PostScript Latin-1 fonts". To use this from the command line for conversions, add --export-to-format=eps-builtin to the command line.

Note that this export doesn't support other encodings than Latin-1, and the text size may be somewhat off. Please don't ask us to add other encodings to this. We will not do it. It's an interim solution while we try to get embedded fonts out of Pango (maybe using PangoPDF).

### Compiling

1. Q: Why can't I compile Dia?
A:

In most cases, it is because you have an old version of a support library. The libraries needed to compile Dia version 0.91+ are:

• pkg-config version 0.14.0 or higher.
• GTK version 2.0.0+
• and related libraries (glib, atk, pkg-config, pango).
• Pango version 1.1.5 or higher. Must be compiled with the PangoFT2 module. Pango 1.1.5 and higher depend on GLib version 2.1.3 or higher. PangoFT2 depends on font-config version 1.0.1 or higher.
• libxml version 2.3.9 or higher
• intltool version 0.21 or higher.
• freetype version 2.0.9 or higher on Unix.
Optional libraries that add extra features (for 0.91+):
The libraries needed to compile Dia as of version 0.90 are:

• Glib version 1.2.0+ (required by GTK)
• GTK version 1.2.0+
• Gdk-Pixbuf version 0.7.0+ (can be replaced with Imlib version 1.8.0+)
• libxml version 1.8.5+
• intltool version 0.12 or higher.
• libunicode
• version 0.4 (not the version 0.7 available at SourceForge).
Optional libraries that add extra features (for 0.90):
• libpng (for png export support)
• gnome-libs (for Gnome support)
• bonobo (for document embedding support, requires Gnome)
• freetype version 2.0.9 or higher, for better font support.
• libart version 2.1.0 or higher, for antialiasing and PNG export support.

Note that if you use some package system (dpkg or RPM), you will need to download the development packages (-dev or -devel).

Some systems, notably Red Hat and derivatives, don't have /usr/local/lib in /etc/ld.so.conf. GNU applications by default install into /usr/local when compiled. To make Dia work there, either add /usr/local/lib to /etc/ld.so.conf and run ldconfig as root, or configure with --prefix=/usr to put everything in /usr.

2. Q: How can I convert the tar file to an rpm?
A: rpmbuild -ta dia-XXX.tar.gz

3. Q: Can Dia compile on Mac OS X?
A: Yes, on Mac OS X 10.4.2, using fink versions of libtool 1.5.10, autoconf 2.59, and automake 1.9.4, Daniel Rogers has managed to compile Dia 0.94 under Mac. See this mail. It has not been reported to compile with any non-X port of Gtk2.

4. Q: Why does my copy of Dia for Windows die when I try to load it?
A: Because the HOME environment variable is not set. Add a line like this to your autoexec.bat file:
      set HOME=c:\home
then restart your computer and make sure c:\home exists. The path should not contain any spaces and is case-sensitive (c:\Home is not the same as c:\home).

As of Dia 0.88.1, this problem should no longer happen.

5. Q: When printing I get many pages of text starting with: %!PS-Adobe-2.0. What to do?
A: Buy a postscript printer or implement GDI printing ... :-) The other option is to install Ghostscript along with its print redirector so you can have a Windows printer that filters things through gs.

6. Q: How do I make patches for Dia so that they are integrated with minimum delay?
A: Cyrille Chepelov answered this question in depth after yet another impractical patch had arrived on the list. To avoid headaches for everybody, please follow these words of wisdom:

The best way to generate these is to download the tree through anonymous SVN (from cvs.gnome.org, this is possible of course also for Windows with the "Universal Geek user interface device driver" (cygwin)).

Then, all what is necessary is to do cvs adds (commit will of course not be accepted), do a cvs -z3 up -PAd to check that the patch will be as up to date as possible, and issue the following command:
cvs -z3 diff -Nu 2>/tmp/diff.log | gzip >/tmp/some.patch.gz

Study diff.log to check that no files have been unnecessarily touched. zless the patch to check that all changes are accounted for in the ChangeLog and are justified (one patch per orthogonal set of changes is also preferred).

An alternative is to have two copies, one pristine and one work area, of the same tree, preferably a recent CVS snapshot. Modify all files and test in the work area; then make distclean in both trees, and in the directory which contains both trees, do something like :
 diff -urN dia-pristine dia-workarea >/tmp/some.patch grep "^+++" /tmp/some.patch # check that no files have been unnecessarily # touched, added or removed. less /tmp/some.patch # check that patch is correct gzip /tmp/some.patch  Again, this is possible even on a (okay, recent) Macintosh.

Send patch. Don't resend the same version of the patch twice on the list (when replying to yourself with updates...). Keep large patches (> 5-40 kb) for private mails and/or in Bugzilla (URL in the mailing list is of course welcome; small patches are okay, especially if some discussion on them is sought).

7. Q: After compiling, when I run Dia it fails with the following error:
"Couldn't find standard objects when looking for object-libs, exiting..."


A: You're trying to run the Dia executable directly from the source directories. Either do make install, or run with the wrapper script app/run_dia.sh. That way, Dia will know where to find its objects.

### Extending Dia

1. Q: How do I add new shapes/sheets?
A: An explanation is given in doc/custom-shapes in the source distribution on how the shape format works.

However, Dia now also has the capability of exporting a diagram as a shape. Each collection of shapes (called a sheet) should be kept together in a subdirectory of ~/.dia/shapes, e.g, ~/.dia/shapes/Engines. To make a shape, first design it in Dia. Then export it into your subdirectory. Two files will be generated, a .shape file and a .png file (the icon).

From version 0.90 and up, Dia features a Sheets and Objects editor which will allow you to load the shape into a sheet. It will also update Dia's loaded objects on the fly.

If you still want to do things by hand, update the corresponding sheet file in ~/.dia/sheets, in this case called Engines.sheet. Example contents of a sheet file is:


<?xml version="1.0" encoding="iso-8859-1"?> <!-- -*- xml -*- -->

<sheet xmlns="http://www.lysator.liu.se/~alla/dia/dia-sheet-ns">
<name>Engines</name>
<description>Mechanical Engines</description>
<contents>
<object name="Engines - Gas">
<description>A gas engine</description>
</object>
</contents>
</sheet>

Each new object should be added to the sheet by adding an object section. Next time you restart Dia, the new objects should show up in the list of sheets.

### Compatibility

1. Q: Can Dia open Visio .vsd files ?
A: No, it can't. Visio file format is a completely proprietary and undocumented file format. So it is really difficult to write code to read it. The now-defunct Software Bazaar offered a bounty of several thousand dollars for reverse-engineering the Visio format. We really would like to be able to do so.

An easier alternative would be to make a Visio plug-in that will allow conversion. Other programs have already done this for their proprietary formats. If somebody were to make such a script, we could set up a public server to do conversions.

With Visio 2002, it has become possible to export Visio diagrams as XML. Microsoft, in their infinite generosity, has even published the Schema. With the new XSLT plug-in, it should be only a question of writing a proper XSLT document to be able to translate.

Ian Redfern is working on decoding the Visio format. If you have any interest in converting Visio files, please give him your assistance.