docs/gnu/README.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4
   5 <chapter id="README">
   6 <title>ADG overview</title>
   7 <subtitle>How to get start with ADG</subtitle>
   8
   9 <simplesect id="README.general">
  10 <title>General information</title>
  11
  12 <para>Automatic Drawing Generation is GObject-based library that provides
  13 a non-interactive cairo canvas specifically designed for generating
  14 technical drawings.</para>
  15
  16 <para>If you want to develop an application that needs to show and print
  17 drawings where some data change but the overall design is always the
  18 same, the ADG library can be quite useful. In manufacturing industries
  19 this is often a good choice and could help to greatly improve the
  20 productivity of technical offices.</para>
  21
  22 <para>You could reach similar targets using parametric CADs but a custom
  23 application provides the following benefits:</para>
  24
  25 <itemizedlist>
  26    <listitem>more customizable;</listitem>
  27    <listitem>quicker and not so bloated as a parametric CAD;</listitem>
  28    <listitem>can be easily connected to a database;</listitem>
  29    <listitem>an ADG based filter can generate drawing on-fly: this feature could
  30    be used in web-based application.</listitem>
  31 </itemizedlist>
  32
  33 <para>For further details, visit the <ulink url="http://adg.entidi.com/">ADG home page</ulink>.</para>
  34
  35 </simplesect>
  36
  37 <simplesect id="README.design">
  38 <title>Design overview</title>
  39
  40 <para>The project grew up around the <ulink url="http://www.gtk.org/">GObject</ulink> library: the
  41 ADG canvas is developed in plain C using the object-oriented approach
  42 supplied by GObject.</para>
  43
  44 <para>The mathematical and geometrical algorithms, together with some useful
  45 function to manipulate cairo paths, are kept in a separated library.
  46 Although the CPML library (Cairo Path Manipulation Library) is scattered
  47 across the ADG tree, it can be easily splitted on its own in future, if
  48 requested.</para>
  49
  50 <para>The rendering is based on the <ulink url="http://cairographics.org/">cairo engine</ulink>,
  51 so the ADG project fully shares strong and weak points of the underlying
  52 cairo library.</para>
  53
  54 <para>For the optional database connectivity, my suggestion is to take a look
  55 to the <ulink url="http://www.gnome-db.org/">libgda</ulink> project, partly because it is a
  56 good and actively maintained project and partly because it uses the ADG
  57 technologies (object-oriented C code using GObject), so can be easily
  58 integrated in a single application.</para>
  59 </simplesect>
  60
  61
  62 <simplesect id="README.dependencies">
  63 <title>External dependencies</title>
  64
  65 <para>The ADG library has the following dependencies:</para>
  66
  67 <itemizedlist>
  68    <listitem><ulink url="http://www.gtk.org/">glib</ulink> 2.10.1 or later</listitem>
  69    <listitem><ulink url="http://cairographics.org/">cairo</ulink> 1.7.4 or later</listitem>
  70    <listitem><ulink url="http://www.gtk.org/">gtk+</ulink> 2.8.0 or later, needed by the demo program</listitem>
  71 </itemizedlist>
  72
  73 <para>These packages should be installed prior to build the ADG: they should
  74 be provided by nearly every decent unix-like system. The ADG is mainly
  75 developed on GNU/Linux systems but its dependecies are known to be cross
  76 platform so a porting should be quite easy (if not automatic).</para>
  77 </simplesect>
  78
  79
  80 <simplesect id="README.installation">
  81 <title>Installation</title>
  82
  83 <para>The ADG build system is based on GNU autotools, the de-facto standard
  84 for managing free software projects.</para>
  85
  86 <orderedlist>
  87    <listitem>Download the ADG tarball and put it somewhere in your file system,
  88    where you have write access (your home directory is a good candidate).
  89    You can browse the old releases or get the latest tarball from
  90    <ulink url="http://sourceforge.net/project/showfiles.php?group_id=185095">sourceforge</ulink>.
  91    </listitem>
  92    <listitem>Unpack the tarball: use the version you downloaded in the previous step
  93    instead of 0.3.2:
  94 <programlisting>tar -xjvf adg-0.3.2.tar.bz2</programlisting></listitem>
  95    <listitem>Configure the build. You can set different options while configuring:
  96    check the output of <code>./configure --help</code> to get all the available options.
  97    Furthermore, the INSTALL file gives you a detailed description of
  98    the common options.
  99 <programlisting>cd adg-0.3.2
 100 ./configure</programlisting></listitem>
 101    <listitem>Build the ADG library.
 102 <programlisting>make</programlisting>
 103    Once the building has finished, you are able to run the demo program
 104    without installing anything. Just try them out:
 105 <programlisting>./demo/adg-demo
 106 ./demo/ldim</programlisting></listitem>
 107    <listitem>Install the ADG library on your system. You must have root privileges
 108    to do that or you have to configure a target directory (the <code>--prefix</code>
 109    option in configure) that is user-writable.
 110 <programlisting>make install</programlisting>
 111    If you have <code>sudo</code> access you can use it by prefixing the installation
 112    command to temporary gain root privileges:
 113 <programlisting>sudo make install</programlisting></listitem>
 114    <listitem>You can uninstall the ADG whenever you want by typing:
 115 <programlisting>make uninstall</programlisting>
 116    from inside the ADG build directory. Just be sure to have the same
 117    privileges you had while installing it.</listitem>
 118 </orderedlist>
 119 </simplesect>
 120
 121 </chapter>