source: general/prog/doxygen.xml@ 9db83697

<?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 " ">
  <!ENTITY doxygen-download-ftp  "ftp://ftp.stack.nl/pub/users/dimitri/doxygen-&doxygen-version;.src.tar.gz">
  <!ENTITY doxygen-md5sum        "5e0b6c8854c87e06aaca78c81c5236ec">
  <!ENTITY doxygen-size          "2.8 MB">
  <!ENTITY doxygen-buildsize     "39.7 MB (additional 10.5 MB to build and install docs and <command>doxywizard</command>)">
  <!ENTITY doxygen-time          "1.26 SBU (additional 0.50 SBU to build docs and <command>doxywizard</command>)">
]>

<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="python"/>, 
    <xref linkend="tex"/>, 
    <xref linkend="gs"/> or <xref linkend="espgs"/>, 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>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 (which 
    includes the man pages), ensure the <application>Python</application>, 
    <application>TeX</application> and <application>GraphViz</application> 
    packages are installed, then substitute the following commands for the 
    <command>make install</command> command above:</para>

<screen role="root"><userinput>make docs &amp;&amp;
make pdf &amp;&amp;
install -v -d -m755 /usr/share/doc/doxygen/src &amp;&amp;
install -v -m644 src/translator{,_adapter,_en}.h \
    /usr/share/doc/doxygen/src &amp;&amp;
install -v -m644 VERSION /usr/share/doc/doxygen &amp;&amp;
make install_docs</userinput></screen>

  </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.</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>

    <para><command>make docs</command>: This command builds the 
    man pages and HTML documentation.</para>

    <para><command>make pdf</command>: This command builds a 
    PDF version of the <application>Doxygen</application> 
    Manual.</para>

    <para><command>install ...</command>: These commands install some files 
    required by the documentation installation.</para>

    <note>
      <para>For documentation in a language other than English, 
      replace the <quote>_en</quote> with the country code of your 
      locale.</para>
    </note>

    <para><command>make install_docs</command>: This command installs 
    the binaries and documentation.</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 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>