docs/adg/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. It can be viewed as a tool for programmatically
  15 representing an abstract model into a layout (<emphasis>2D drafting</emphasis>).</para>
  16
  17 <para>If you want to develop an application that needs to show and print
  18 drawings where some data change but the overall design is similar,
  19 the ADG library can be quite useful. In manufacturing industries
  20 this is often the case and an ADG-based application could help to
  21 greatly improve the productivity of technical offices.</para>
  22
  23 <para>You could reach similar targets using parametric CADs but a custom
  24 application provides the following benefits:</para>
  25
  26 <itemizedlist>
  27    <listitem>more customizable;</listitem>
  28    <listitem>quicker and not so bloated as a parametric CAD;</listitem>
  29    <listitem>can be easily connected to a database;</listitem>
  30    <listitem>an ADG based filter can generate drawing on-fly: this feature
  31    could be used in web-based applications.</listitem>
  32 </itemizedlist>
  33
  34 <para>Visit the <ulink url="http://adg.entidi.com/">ADG web site</ulink> for further
  35 details.</para>
  36
  37 </simplesect>
  38
  39 <simplesect id="README.design">
  40 <title>Design overview</title>
  41
  42 <para>The project is based on the <ulink url="http://www.gtk.org/">GObject</ulink> library:
  43 the ADG canvas is developed in plain C using an object-oriented
  44 approach. Applications based on ADG are not expected to be
  45 developed in C, though: the basic idea is to have a set of language
  46 bindings for higher level languages (the garbage-collected ones,
  47 above all). An application can then be developed using any
  48 specific language available, much in the same way as
  49 <ulink url="http://www.gnome.org/">GNOME</ulink> applications are conceived.
  50 Lua bindings based on <ulink url="http://github.com/pavouk/lgi">LGI</ulink> are
  51 yet availables and effectively used upstream to test the APIs.
  52 The <ulink url="http://dev.entidi.com/p/adg-lua/">adg-lua</ulink> project
  53 provides code examples on how to use them.</para>
  54
  55 <para>The mathematical and geometrical algorithms, together with a bunch
  56 of other useful functions for manipulating cairo paths, are kept
  57 in a separated library called <ulink url="http://adg.entidi.com/cpml/">CPML</ulink>
  58 (Cairo Path Manipulation Library). Although actually embedded into
  59 the ADG project, this library can be easily splitted on its own,
  60 if needed.</para>
  61
  62 <para>The rendering leverages <ulink url="http://cairographics.org/">cairo</ulink>, so the
  63 ADG canvas fully shares strong and weak points of that library.
  64 Most notably, the availables export formats include PostScript,
  65 SVG, PDF, PNG but no CAD specific ones (such as DXF). A complete
  66 list can be <ulink url="http://cairographics.org/backends/">browsed online</ulink>.</para>
  67 </simplesect>
  68
  69
  70 <simplesect id="README.dependencies">
  71 <title>External dependencies</title>
  72
  73 <para>The ADG library has the following dependencies:</para>
  74
  75 <itemizedlist>
  76    <listitem><ulink url="http://cairographics.org/">cairo</ulink> 1.7.4 or later, required by
  77    either CPML and ADG;</listitem>
  78    <listitem><ulink url="http://www.gtk.org/">GLib</ulink> 2.10.1 or later, required by ADG;</listitem>
  79    <listitem><ulink url="http://www.gtk.org/">GTK+</ulink> 3.0.0 or later (or GTK+ 2.12.0 or
  80    later for GTK+2 support) to optionally include GTK+ support and
  81    build the <command>adg-demo</command> program;</listitem>
  82    <listitem><ulink url="http://www.pango.org/">pango-cairo</ulink> 1.18.0 or later (optional)
  83    to support a serious engine for rendering text instead of using
  84    the default cairo "toy" APIs;</listitem>
  85    <listitem><ulink url="http://www.gtk.org/gtk-doc/">gtk-doc</ulink> 1.12 or later (optional),
  86    used to regenerate the API documentation</listitem>
  87    <listitem><ulink url="http://live.gnome.org/GObjectIntrospection">GObject introspection</ulink>
  88    0.9.5 or later (optional) to dinamically generate bindings
  89    metadata.</listitem>
  90 </itemizedlist>
  91
  92 <para>The required packages must be installed prior the ADG building:
  93 they should be availables on nearly every decent unix-like system.</para>
  94
  95 <para>The ADG is mainly developed on GNU/Linux but its dependecies are
  96 known to be cross platform so a porting should be quite easy, if
  97 not automatic. Anyway, the cross-compilation of a Windows
  98 installer is supported upstream and it is based on the ArchLinux
  99 <ulink url="http://github.com/ntd/aur-fedora-mingw">Fedora mingw port</ulink>.</para>
 100 </simplesect>
 101
 102
 103 <simplesect id="README.installation">
 104 <title>Installation</title>
 105
 106 <para>The ADG build system is based on GNU autotools, the de-facto
 107 standard for handling free software projects. The following
 108 step-by-step instructions are included only for reference: you are
 109 free to install ADG in the way you prefer. Just remember if you
 110 are copying and pasting to put the proper package version instead
 111 of the <code>0.6.0</code> placeholder used in the examples.</para>
 112
 113 <orderedlist>
 114    <listitem>Download the ADG tarball and put it somewhere into your file
 115    system (your home directory is a good candidate). You can
 116    browse the old releases or get the latest tarball directly
 117    from <ulink url="http://sourceforge.net/projects/adg/files/">SourceForge</ulink>.
 118 <programlisting>cd $HOME
 119 wget http://sourceforge.net/projects/adg/files/adg/0.6.0/adg-0.6.0.tar.bz2</programlisting></listitem>
 120    <listitem>Unpack the tarball:
 121 <programlisting>tar xjvf adg-0.6.0.tar.bz2</programlisting></listitem>
 122    <listitem>Configure the build. You can set different options while
 123    configuring: check the output of <code>./configure --help</code> to get a
 124    list of all the available customizations.
 125 <programlisting>cd adg-0.6.0
 126 ./configure</programlisting></listitem>
 127    <listitem>Build the ADG library.
 128 <programlisting>make</programlisting></listitem>
 129    <listitem>Once the building has finished, you are able to run the demo
 130    program without installing anything. Just try it out by
 131    launching the uninstalled executable:
 132 <programlisting>demo/adg-demo-uninstalled</programlisting></listitem>
 133    <listitem>Install the library. You must have root privileges, either
 134    by previously logging in as root or by using the <command>sudo</command> command,
 135    if you intend to install it system-wide (the default). Anyway
 136    you can install to a custom destination where you have write
 137    access by explicitely setting the <code>--prefix</code> option in the
 138    configuration step.
 139 <programlisting>sudo make install</programlisting></listitem>
 140 </orderedlist>
 141
 142 <para>Further details on the installation are availables in the <filename>INSTALL</filename>
 143 text file distributed within the tarball.</para>
 144 </simplesect>
 145
 146 </chapter>