UMLGraph/doc/faq.xml

<?xml version="1.0" ?>
<!-- $Id$ -->
<notes>

<!--
To update the table of contents execute the following vim command from a register
/^<h2>Contents
jjma/ul>
kmb/^$
"qyy:g/^<h2><a name/s,<h2><a name="\([^>]*\)>\(.*\)</a></h2>,<li> <a href="\#\1>\2</a></li>,|y Q|u
'ad'b"qP
-->

<h2>Contents</h2>
<ul>

<li> <a href="#cmdline">What is the command line sequence to generate a UMLGraph class diagram?</a></li>
<li> <a href="#utfsvg">Why are the SVG diagrams dot generates malformed?</a></li>
<li> <a href="#antialias">How can I improve the quality of the bitmap images I generate?</a></li>
<li> <a href="#layout">How can I improve the layout of my class diagrams?</a></li>
<li> <a href="#mclass">A class appears multiple times in a class diagram.  Why?</a></li>
<li> <a href="#static">Shouldn't static fields appear underlined?</a></li>
<li> <a href="#winpic">Where can I find a <em>pic2plot</em> executable for Windows?</a></li>
<li> <a href="#cr">Under Windows the output of <em>pic2plot</em> appears empty.  Why?</a></li>
<li> <a href="#maven">I have a problem with Maven's Dotuml plugin.  Can you help me?</a></li>
<li> <a href="#autopic">How can I make the UMLGraph doclet generate sequence diagrams?</a></li>
<li> <a href="#packname">Why the vanity package name?  Why not name the package org.umlgraph?</a></li>
<li> <a href="#unnamed">Why do the options specified in the <code>UMLOptions</code> class stop working, when I pass the <code>packagenames</code> option to <em>javadoc</em>?</a></li>
<li> <a href="#tiger">Why doesn't UMLGraph run under Mac OS X?</a></li>
<li> <a href="#cpp">Can I create UML class diagrams from C++ code?</a></li>
<li> <a href="#ClassCastException">How can I get around a UMLGraphDoc crash with a ClassCastException?</a></li>
</ul>

<h2><a name="cmdline">What is the command line sequence to generate a UMLGraph class diagram?</a></h2>
Assuming that you diagram's description is in the file Diag.java,
issue the commands:
<fmtcode ext="sh">
javadoc -docletpath absolute-path-to/UmlGraph.jar -doclet gr.spinellis.umlgraph.doclet.UmlGraph -output Diag.dot Diag.java
dot -Tpng -oDiag.png Diag.dot
</fmtcode>
In the above you can change <code>png</code> to another file format,
and add more UMLGraph switches before the <code>-option</code> switch.


<h2><a name="utfsvg">Why are the SVG diagrams dot generates malformed?</a></h2>
UMLGraph uses guillemot characters for representing the angle brackets around
stereotypes, as in «interface».
By default these are encoded as ISO-8859-1 characters, which are illegal
in the UTF-8 output that dot generates for SVG.
When using dot to generate SVG output, you should also specify
<code>-outputencoding utf8</code> to UMLGraph.

<h2><a name="antialias">How can I improve the quality of the bitmap images I generate?</a></h2>

Both
<em>dot</em> and
<em>pic2plot</em> can directly produce bitmap images in
formats like GIF, PNG and PNM.
However, if you want to produce presentation-quality output
the a vector output format like Postscript or SVG is preferable.
If you do require a bitmap format, it might be worth to create
it at a higher resolution from a Postscript image, and then downsample it.
This procedure (used for the diagrams appearing on the UMLGraph web site)
will create an antialiased image of a higher quality than what the default
bitmap output options produce.
The following pipeline is an example of how you can achieve this
effect:
<fmtcode ext="sh">
dot -Tps FILENAME.dot |
gs -q -r360 -dNOPAUSE -sDEVICE=pnm -sOutputFile=-  - -c quit |
pnmcrop |
pnmscale 0.25 |
ppmtogif >FILENAME.gif
</fmtcode>
(David Griffiths reports that he had to add to the <em>gs</em> command
<code>-sPAPERSIZE=a4</code> or
<code>-dDEVICEHEIGHTPOINTS=1000</code> to avoid getting
his resutls chopped-off.)

<p />
One other possibility for converting the sequence diagram into Postscript
is to pass it through <em>pic</em> and <em>groff</em>.
Tools like <em>ps2epsi</em> and <em>ps2eps</em> can then be used to
convert the Postscript into encapsulated Postscript.
Of course, <em>groff</em> users will just use the <em>pic</em>
program as part of their processing pipeline.

<h2><a name="layout">How can I improve the layout of my class diagrams?</a></h2>
Try manipulating the <em>dot</em> parameters ratio, minlen, ranksep, and
nodesep.
For example, Arnaud Rogues recommends running <em>dot</em> with
command-line arguments as follows.
<fmtcode ext="sh">
dot -Gratio=0.7 -Eminlen=2
</fmtcode>

<h2><a name="mclass">A class appears multiple times in a class diagram.  Why?</a></h2>
Most probably your class diagram uses packages, and you are not
qualifying the classes with the respective package names in the
tags you use.
The tags are not smart enough to do the package resolution,
so you will have to prepend the package name to the class,
or avoid using packages.
<p />
<h3>Problematic Specification</h3>
<fmtcode ext="java">
package test;
abstract class AbstractNode {}
/** @composed 1 has * AbstractNode */
class InnerNode extends AbstractNode {}
class Leaf extends AbstractNode {}
</fmtcode>
<h3>First Approach: Class Name Qualified with the Package</h3>
<fmtcode ext="java">
package test;
abstract class AbstractNode {}
/** @composed 1 has * test.AbstractNode */
class InnerNode extends AbstractNode {}
class Leaf extends AbstractNode {}
</fmtcode>
<h3>Second Approach: No Package Specification</h3>
<fmtcode ext="java">
abstract class AbstractNode {}
/** @composed 1 has * test.AbstractNode */
class InnerNode extends AbstractNode {}
class Leaf extends AbstractNode {}
</fmtcode>

<h2><a name="static">Shouldn't static fields appear underlined?</a></h2>
Yes they should.
Unfortunately, <em>dot</em> does not (yet) support a way to underline
single labels, and thus <em>UMLGraph</em> can not show the static fields
underlined.


<h2><a name="winpic">Where can I find a <em>pic2plot</em> executable for Windows?</a></h2>
A port of <em>pic2plot</em> for Windows can be found in
GNU PlotUtils, which is part of the
<a href="http://gnuwin32.sourceforge.net/packages.html">GnuWin32</a>
project.

<h2><a name="cr">Under Windows the output of <em>pic2plot</em> appears empty.  Why?</a></h2>
On Windows platforms note that the current version of
<em>pic2plot</em> appears to be very picky about carriage return (CR - \r)
characters (by default, CR is part of the platform's end of line sequence)
appearing in its input file.
Therefore, you will probably want to instruct your editor to create
Unix-style files, or filter the files to remove the carriage return
characters.
The following Perl invocation is such a filter:
<fmtcode ext="sh">
perl -p -e "BEGIN {binmode(STDOUT);} s/\r//"
</fmtcode>
In addition, <em>pic2plot</em> appears to require that the last input file
be properly terminated (with a newline).
Apparently, some Windows editors may leave the last line unterminated,
so if your editor is in this category it may be safer to add a blank line
in the end.

<h2><a name="maven">I have a problem with Maven's Dotuml plugin.  Can you help me?</a></h2>
Sorry, I did not develop this plugin, and therefore can not offer help.
Have a look at the project's documentation and mailing lists available through
<a href="http://maven-plugins.sourceforge.net/maven-dotuml-plugin/">plugin web page</a>.

<h2><a name="autopic">How can I make the UMLGraph doclet generate sequence diagrams?</a></h2>
You can't.
You have to write the <em>pic</em> code for the sequence diagrams by hand.

<h2><a name="packname">Why the vanity package name?  Why not name the package org.umlgraph?</a></h2>
The package names are supposed to be unique.
If everybody names their project under the org.* namespace there's
no mechanism for ensuring that the name will be unique,
unless the developer also registers the corresponding domain name.
Registering a different domain name for each project is not practical,
therefore I name the packages I develop using the domain name I own.

<h2><a name="unnamed">Why do the options specified in the <code>UMLOptions</code> class stop working, when I pass the <code>packagenames</code> option to <em>javadoc</em>?</a></h2>
When you pass the <code>packagenames</code> option to
<em>javadoc</em>, the default (unnamed) package (and the
<code>UMLOptions</code> class
located in it) is ignored.
In such cases you should include the <code>UMLOptions</code> class
within a named package.

<h2><a name="tiger">Why doesn't UMLGraph run under Mac OS X?</a></h2>
Make sure you are running Java 1.5 (run <code>java -version</code> to see).
If you are not running 1.5 you may need to adjust the symbolic links
in
<code>/System/Library/Frameworks/JavaVM.framework/Versions</code>.

<h2><a name="cpp">Can I create UML class diagrams from C++ code?</a></h2>
This <a href="http://www.spinellis.gr/blog/20060921/">blog entry</a> describes
a simple solution that has worked for me.
Depending on your requirements YMMV.

<h2><a name="ClassCastException">How can I get around a UMLGraphDoc crash with a ClassCastException?</a></h2>
This happens due to a know <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6442982">javadoc bug</a>.
By fixing the classpath used for the UNLGraph invocation you can avoid this
problem.
Olivier Duysens notes:
<blockquote>
JBuilder users need to go to Preferences/Build/Ant,
and tick the box "Use project libraries when running ant" to solve the issue.
</blockquote>

</notes>