source: general/prog/doxygen.xml@ 3c3fbe6

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY doxygen-download-http "http://ftp.stack.nl/pub/users/dimitri/doxygen-&doxygen-version;.src.tar.gz">
  <!ENTITY doxygen-download-ftp  "ftp://ftp.stack.nl/pub/users/dimitri/doxygen-&doxygen-version;.src.tar.gz">
  <!ENTITY doxygen-md5sum        "6cad81b86c1271777b8ee7c953a496ac">
  <!ENTITY doxygen-size          "2.7 MB">
  <!ENTITY doxygen-buildsize     "41 MB (additional 6.3 MB to install docs)">
  <!ENTITY doxygen-time          "1.4 SBU">
]>

<sect1 id="doxygen" xreflabel="Doxygen-&doxygen-version;">
  <?dbhtml filename="doxygen.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Doxygen-&doxygen-version;</title>

  <indexterm zone="doxygen">
    <primary sortas="a-Doxygen">Doxygen</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Doxygen</title>

    <para>The <application>Doxygen</application> package contains a
    documentation system for C++, C, Java, Objective-C, Corba IDL and to some
    extent PHP, C# and D. This is useful for generating HTML documentation
    and/or an off-line reference manual from a set of documented source files.
    There is also support for generating output in RTF, PostScript, hyperlinked
    PDF, compressed HTML, and Unix man pages. The documentation is extracted
    directly from the sources, which makes it much easier to keep the
    documentation consistent with the source code.</para>

    <para>You can also configure <application>Doxygen</application> to extract
    the code structure from undocumented source files. This is very useful to
    quickly find your way in large source distributions. Used along with
    <application>GraphViz</application>, you can also visualize the relations
    between the various elements by means of include dependency graphs,
    inheritance diagrams, and collaboration diagrams, which are all generated
    automatically.</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&doxygen-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&doxygen-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &doxygen-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &doxygen-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &doxygen-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &doxygen-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Doxygen Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para><xref linkend="qt"/>,
    <xref linkend="tex"/> and
    <ulink url="http://www.graphviz.org/">GraphViz</ulink></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Doxygen</title>

    <para>Install <application>Doxygen</application> by running the following
    commands:</para>

<screen><userinput>rm src/unistd.h &amp;&amp;
./configure --prefix /usr --docdir /usr/share/doc &amp;&amp;
make</userinput></screen>

    <para>This package does not come with a test suite.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install</userinput></screen>

    <para>If you wish to generate and install the package documentation
    (note that man pages have already been installed), you must have
    <application>TeX</application> installed, then issue the following
    command as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install_docs</userinput></screen>

    <tip>
      <para>If you don't have <application>TeX</application> installed but
      wish to generate and install the HTML documentation (very good docs),
      issue the following commands:</para>

<screen><userinput>make docs</userinput></screen>

      <para>Now, as the <systemitem class="username">root</systemitem>
      user:</para>

<screen role="root"><userinput>install -v -m755 -d /usr/share/doc/doxygen &amp;&amp;
cp -v -R examples html /usr/share/doc/doxygen</userinput></screen>

    </tip>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><command>rm src/unistd.h</command>: There is a bug in
    <application>Flex</application>-2.5.31 which causes
    <command>make</command> to use this file instead of the system
    installed version. Removing this file allows the GUI front-end to build
    successfully. This command is not required if you don't pass the
    <option>--with-doxywizard</option> parameter (but won't affect the build
    otherwise).</para>

    <para><option>--with-doxywizard</option>: Use this parameter if
    <application>Qt</application> is installed and you wish to build the
    GUI front-end.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Doxygen</title>

    <para>There is no real configuration necessary for the
    <application>Doxygen</application> package although three additional
    packages are required if you wish to use extended capabilities. If you
    need to use the language translation features, you must have
    <xref linkend="python"/> installed. If you require formulas to
    create PDF documentation, then you must have <xref linkend="tex"/>
    installed. If you require formulas to convert PostScript files to bitmaps,
    then you must have <xref linkend="gs"/> or <xref linkend="espgs"/>
    installed.</para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directory</segtitle>

      <seglistitem>
        <seg>doxygen, doxytag, and optionally, doxywizard</seg>
        <seg>None</seg>
        <seg>/usr/share/doc/doxygen</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="doxygen-prog">
        <term><command>doxygen</command></term>
        <listitem>
          <para>is a command-line based utility used to generate template
          configuration files and then generate documentation from these templates. Use
          <command>doxygen --help</command> for an explanation of the command-line
          parameters.</para>
          <indexterm zone="doxygen doxygen-prog">
            <primary sortas="b-doxygen">doxygen</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="doxytag">
        <term><command>doxytag</command></term>
        <listitem>
          <para>is used to generate a tag file and/or a search index for a set
          of HTML files.</para>
          <indexterm zone="doxygen doxytag">
            <primary sortas="b-doxytag">doxytag</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="doxywizard">
        <term><command>doxywizard</command></term>
        <listitem>
          <para>is a GUI front-end for configuring and
          running <command>doxygen</command>.</para>
          <indexterm zone="doxygen doxywizard">
            <primary sortas="b-doxywizard">doxywizard</primary>
          </indexterm>
        </listitem>
      </varlistentry>
    </variablelist>

  </sect2>

</sect1>