root/gaphor-doc/trunk/gaphor-project-documentation.xml

<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
>
<chapter id="chap-project-documentation">
  <title>Using <application>Gaphor</application> diagrams in project documentation</title>

  <para>
    Diagrams created with <application>Gaphor</application> can be easily used in your project
    documentation. It can be done in two ways
    <itemizedlist>
      <listitem><simpara>exporting diagram from <application>Gaphor</application></simpara></listitem>
      <listitem><simpara>
        converting diagrams included in <application>Gaphor</application> file into
        PDF or SVG files using <command>gaphorconvert</command> commandline utility
      </simpara></listitem>
    </itemizedlist>
    This chapter describes how to create high quality documents
    using second approach.
  </para>

  <section id="sect-project-documentation-gaphor-convert">
    <title>Converting <application>Gaphor</application> files</title>
    <para>
      <application>Gaphor</application> installation includes
      <command>gaphorconvert</command> utility. This utility takes list of
      <application>Gaphor</application> files and converts them into PDF or
      SVG files.
    </para>
    <para>
      <application>Gaphor</application> file contains several diagrams. Every
      diagram is included in some package
      (see  <xref linkend="sect-tree-view"/>).
      Using <command>gaphorconvert</command> utility 
      you will get diagram files in desired format (PDF by default), which reflect
      structure of your <application>Gaphor</application> file.
    </para>
    <figure id="fig-packages-and-diagrams-example" float="1">
      <title>Packages with diagrams</title>
      <graphic fileref="packageswithdiagrams.png"/>
    </figure>
    <para>
      For example you can have
      structure like on <xref linkend="fig-packages-and-diagrams-example"/>.
      Processing <application>Gaphor</application> file with
      <command>gaphorconvert</command> utility
      <informalexample>
        <programlisting>
gaphorconvert -u <ulink url="project-documentation-example.gaphor">project-documentation-example.gaphor</ulink>
        </programlisting>
      </informalexample>
      will give you list of files
      <informalexample>
        <screen>
Documentation_Example/DocBook/Classes.pdf
Documentation_Example/Overview.pdf
        </screen>
      </informalexample>
      You can also put files to some subdirectory (creating SVG files, now)
      with command
      <informalexample>
        <programlisting>
gaphorconvert -u -d diagrams -f svg <ulink url="project-documentation-example.gaphor">project-documentation-example.gaphor</ulink>
        </programlisting>
      </informalexample>
      which will give you
      <informalexample> <!--fixme-->
        <screen>
diagrams/Documentation_Example/DocBook/Classes.svg
diagrams/Documentation_Example/Overview.svg
        </screen>
      </informalexample>
    </para>
    <para>
      See <command>gaphorconvert</command> help screen for more options
      <informalexample>
        <programlisting>
gaphorconvert -h
        </programlisting>
      </informalexample>
    </para>
  </section>

  <section id="sect-project-documentation-tex">
    <title>TeX/LaTeX using pdfTeX</title>

    <para>
      Most Unix operating systems come with decent
      <ulink url = "http://www.tug.org/">TeX</ulink> distribution installation.
      <ulink url = "http://www.tug.org/">TeX</ulink> distribution like
      <ulink url = "http://www.tetex.org/">teTeX</ulink> includes
      <ulink url = "http://www.pdftex.org/">pdfTeX</ulink> support, which
      allows to create high quality PDF files.
    </para>
    <para>
      <application>pdfTeX</application> support means that you can include
      PDF files in your documents using <literal>graphicx</literal> package and
      <command>\includegraphics</command> command.
    </para>
    <para>
      Taking as an example <application>Gaphor</application> file from
      <xref linkend="sect-project-documentation-gaphor-convert"/> you can
      process gaphor file with command
      <informalexample>
        <programlisting>
gaphorconvert -u -d pdfdiagrams <ulink url="project-documentation-example.gaphor">project-documentation-example.gaphor</ulink>
        </programlisting>
      </informalexample>
      and include one of diagrams in <application>LaTeX</application>
      document, see <xref linkend="ex-latex-include-diagram"/>.
      Finally, create PDF file
      <informalexample>
        <programlisting>
pdflatex <ulink url="texexample.tex">texexample.tex</ulink>
        </programlisting>
      </informalexample>

      <example id="ex-latex-include-diagram">
        <title>Including Gaphor diagram in LaTeX document</title>
        <programlisting>
\begin{figure}
    \includegraphics[width=.8\textwidth]{pdfdiagrams/Documentation_Example/DocBook/Classes}
    \caption{DocBook documentation example}\label{fig:docbook}
\end{figure}
        </programlisting>
      </example>
    </para>
    <!--para>
      Example files can be downloaded
      <itemizedlist>
        <listitem><simpara>
            <ulink url="project-documentation-example.gaphor">project-documentation-example.gaphor</ulink>
        </simpara></listitem>
        <listitem><simpara>
            <ulink url="texexample.tex">texexample.tex</ulink>
        </simpara></listitem>
      </itemizedlist>
      using above links.
    </para-->
    <para>
      For more information about including graphic files in
      <application>LaTeX</application> documents see
      &quot;Using Imported Graphics in LaTeX 2e&quot; by Keith Reckdahl,
      which is usually provided with <application>TeX</application>
      distribution installed on your operating system (look for
      <filename>epslatex.ps</filename> file).
    </para>
    <section id="sect-project-documentation-latex-advanced">
      <title>Advanced <application>LaTeX</application> usage</title>
      <para>
        While creating <application>LaTeX</application> documents it can
        be desirable to distinguish between UML diagrams and common figures.
        Using <literal>float</literal>
        <application>LaTeX</application> package you can create new
        <application>LaTeX</application> environment specific for UML diagrams, see
        <xref linkend="ex-latex-use-float"/>.
      </para>
      <example id="ex-latex-use-float">
        <title>Diagram LaTeX environment</title>
        <programlisting>
\newfloat{diagram}{ht}{drg}
\floatname{diagram}{Diagram}

...

\begin{diagram}
  \includegraphics[width=.8\textwidth]{pdfdiagrams/Documentation_Example/DocBook/Classes}
  \caption{DocBook documentation example}\label{diag:docbook}
\end{diagram}

...

% generate list of diagrams
\listof{diagram}{List of Diagrams}
        </programlisting>
      </example>
      <para>
        Example file can be downloaded using following link 
        <ulink url="texfloatexample.tex">texfloatexample.tex</ulink>.
      </para>
      <para>
        See also
        <literal>float</literal> <application>LaTeX</application>
        package documentation &quot;An Improved Environment
        for Floats&quot; by Anselm Lingnau.
      </para>
    </section>
  </section>

  <section id="sect-project-documentation-docbook">
    <title>DocBook</title>
    <para>
      (to be done using svg files, first let&apos;s change gaphor manual to use
      them)
    </para>
  </section>
</chapter>
<!-- vi:sw=2:tw=78:tabstop=2:sts=2
-->