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 (required)</listitem>
  69    <listitem><ulink url="http://cairographics.org/">cairo</ulink> 1.7.4 or later (required)</listitem>
  70    <listitem><ulink url="http://www.gtk.org/">gtk+</ulink> 2.12.0 or later (optional), needed by
  71    the <command>adg-demo</command> program</listitem>
  72    <listitem><ulink url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink> 1.9 or later (optional),
  73    used to regenerate the API documentation</listitem>
  74 </itemizedlist>
  75
  76 <para>The required packages must be installed prior the ADG building: they should
  77 be provided by nearly every decent unix-like system. The ADG is mainly
  78 developed on GNU/Linux systems but its dependecies are known to be cross
  79 platform so a porting should be quite easy (if not automatic).</para>
  80 </simplesect>
  81
  82
  83 <simplesect id="README.installation">
  84 <title>Installation</title>
  85
  86 <para>The ADG build system is based on GNU autotools, the de-facto standard
  87 for managing free software projects.</para>
  88
  89 <orderedlist>
  90    <listitem>Download the ADG tarball and put it somewhere in your file system,
  91    where you have write access (your home directory is a good candidate).
  92    You can browse the old releases or get the latest tarball from
  93    <ulink url="http://sourceforge.net/projects/adg/files/">sourceforge</ulink>.
  94    </listitem>
  95    <listitem>Unpack the tarball. Use the version you downloaded in the previous step
  96    instead of 0.6.0:
  97 <programlisting>tar xjvf adg-0.6.0.tar.bz2</programlisting></listitem>
  98    <listitem>Configure the build. You can set different options while configuring:
  99    check the output of <code>./configure --help</code> to get all the available options.
 100    Furthermore, the INSTALL file gives you a detailed description of
 101    the common options.
 102 <programlisting>cd adg-0.6.0
 103 ./configure</programlisting></listitem>
 104    <listitem>Build the ADG library.
 105 <programlisting>make</programlisting>
 106    Once the building has finished, you are able to run the demo program
 107    without installing anything. Just try it out:
 108 <programlisting>./demo/adg-demo</programlisting></listitem>
 109    <listitem>Install the ADG library on your system. You must have root privileges
 110    to do that or you have to configure a target directory (the <code>--prefix</code>
 111    option in configure) that is user-writable.
 112 <programlisting>make install</programlisting>
 113    If you have <code>sudo</code> access you can use it by prefixing the installation
 114    command to temporary gain root privileges:
 115 <programlisting>sudo make install</programlisting></listitem>
 116    <listitem>You can uninstall the ADG whenever you want by typing:
 117 <programlisting>make uninstall</programlisting>
 118    from inside the ADG build directory (or <code>sudo make uninstall</code>). Just
 119    be sure to have the same privileges you had when installing it.</listitem>
 120 </orderedlist>
 121 </simplesect>
 122
 123 </chapter>