<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry>
  <refentryinfo>
    <date>2008-Dec-13</date>

    <author>
      <firstname>Steve</firstname>

      <surname>McInerney</surname>

      <email>steve@stedee.id.au</email>
    </author>

    <author>
      <firstname>Alexander</firstname>

      <surname>Lazic</surname>

      <email>al-awffull@none.at</email>
    </author>

    <author>
      <firstname>Patrick</firstname>

      <surname>Ben Koetter</surname>

      <email>p@state-of-mind.de</email>
    </author>

    <author>
      <firstname>Benoit</firstname>

      <surname>Rouits</surname>

      <email>brouits@free.fr</email>
    </author>

    <author>
      <firstname>Stanislaw</firstname>

      <surname>Yurievich Pusep</surname>
    </author>

    <author>
      <firstname>Bradford</firstname>

      <surname>L. Barrett</surname>

      <email>brad@mrunix.net</email>
    </author>
  </refentryinfo>

  <refmeta>
    <refentrytitle>awffull</refentrytitle>

    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>AWFFull</refname>

    <refpurpose>A Webalizer Fork, Full o' features</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>awffull</command>

      <arg>...</arg>

      <arg>log-file</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id="description">
    <title>Description</title>

    <para><productname>AWFFull</productname> is a web server log analysis
    program based on <productname>The Webalizer</productname>.
    <application><productname>AWFFull</productname></application> produces
    usage statistics in HTML format for viewing with a browser. The results
    are presented in both columnar and graphical format, which facilitates
    interpretation. Yearly, monthly, daily and hourly usage statistics are
    presented, along with the ability to display usage by site, URL, referrer,
    user agent (browser), user name, search strings, entry/exit pages, and
    country (some information may not be available if not present in the log
    file being processed).</para>

    <para><productname>AWFFull</productname> supports the following log
    formats shown in the following variable list:</para>

    <variablelist>
      <varlistentry>
        <term>CLF</term>

        <listitem>
          <para>(common log format) log files</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Combined</term>

        <listitem>
          <para>log formats as defined by <acronym>NCSA</acronym> and others,
          and variations of these which it attempts to handle
          intelligently</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>xferlog</term>

        <listitem>
          <para><application>wu-ftpd</application> formatted log files
          allowing analysis of ftp servers, and
          <application>squid</application> proxy logs.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <note>
      <para>Logs may also be compressed, via <command>gzip</command>. If a
      compressed log file is detected, it will be automatically uncompressed
      while it is read. Compressed logs must have the standard
      <application><command>gzip</command></application> extension of
      <filename><filename>.gz</filename></filename>.</para>
    </note>

    <para>This documentation applies to
    <productname><application>AWFFull</application></productname> Version
    3.8.2</para>
  </refsect1>

  <refsect1 id="changes_from_webalizer">
    <title>Changes From WEBALIZER</title>

    <para><productname>AWFFull</productname> is based on <productname>The
    Webalizer</productname> code and has a number of large and small changes.
    These include:</para>

    <itemizedlist>
      <listitem>
        <para>Beyond the raw statistics: Making use of published formulae to
        provide additional insights into site usage</para>
      </listitem>

      <listitem>
        <para>GeoIP IP Address look-ups for more accurate country
        detection</para>
      </listitem>

      <listitem>
        <para>Resizable graphs</para>
      </listitem>

      <listitem>
        <para>Integration with GNU gettext allowing for ease of translations.
        Currently 32 languages are supported.</para>
      </listitem>

      <listitem>
        <para>Display more than 12 months of the site history on the front
        page.</para>
      </listitem>

      <listitem>
        <para>Additional page count tracking and sort by same.</para>
      </listitem>

      <listitem>
        <para>Some minor visual tweaks, including Geolizer's use of Kb, Mb etc
        for Volumes</para>
      </listitem>

      <listitem>
        <para>Additional Pie Charts for URL counts, Entry and Exit Pages, and
        Sites</para>
      </listitem>

      <listitem>
        <para>Horizontal lines on graphs that are more sensible and easier to
        read</para>
      </listitem>

      <listitem>
        <para>User Agent and Referral tracking is now calculated via PAGES not
        HITS</para>
      </listitem>

      <listitem>
        <para>GNU style long command line options are now supported (eg
        <option>--help</option>)</para>
      </listitem>

      <listitem>
        <para>Can choose what is a page by excluding <quote>what isn't</quote>
        vs the original <quote>what is</quote> method</para>
      </listitem>

      <listitem>
        <para>Requests to the site being analysed are displayed with the
        matching referring URL</para>
      </listitem>

      <listitem>
        <para>A Table of 404 Errors, and the referring URL can be
        generated</para>
      </listitem>

      <listitem>
        <para>An external CSS file can be used with the generated html</para>
      </listitem>

      <listitem>
        <para>Manual performance optimisation of the config file is now easier
        with a post analysis summary output</para>
      </listitem>

      <listitem>
        <para>Specified IP Addresses can be assigned to a given country</para>
      </listitem>

      <listitem>
        <para>Additional Dump options for detailed analysis with other
        tools</para>
      </listitem>

      <listitem>
        <para>Lotus Domino v6 logs are now detected and processed</para>
      </listitem>
    </itemizedlist>

    <para>Additional changes and improvements are planned and undergoing
    implementation. See the TODO file for details.</para>
  </refsect1>

  <refsect1 id="new_report_measurements">
    <title>New Report Measurements</title>

    <para>With version 3.8.1 of <productname>AWFFull</productname>, several
    new measured results have been added to the detailed report monthly
    page.</para>

    <variablelist>
      <varlistentry>
        <term>Single Access</term>

        <listitem>
          <para>Single Access Pages - the only page seen within a given
          visit</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Stickiness</term>

        <listitem>
          <para>How useful a given entry page is to draw Visitors deeper into
          your site</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Popularity</term>

        <listitem>
          <para>The Ratio of Page Entries to Page Exits</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>These metrics can help towards improving insight in the usage of the
    processed web site. And hence allow the site owner to make positive change
    to make the site more useful to site visitors. All three metrics appear in
    the <quote>Entry Pages</quote> Report. <quote>Popularity</quote> is also
    on the <quote>Exit Pages</quote> Report.</para>

    <bridgehead>Single Access</bridgehead>

    <para>More completely: <quote>Single Access Pages</quote>. This is a
    report on the number of times that a given page was the only page viewed
    within a Visit. Or in English, Someone came to your website. They only
    viewed one page. The number is the cumulative count of people who did this
    for that particular page. Why is this useful? Identifying those entry
    pages that don't draw visitors deeper into your site. Or seeing entry
    pages that shouldn't be entry pages. It's also a reality check against the
    next two values which are calculated from this number. The number
    generated should be a subset of the <quote>Entry Page Views</quote> and/or
    <quote>Exit Page Views</quote> metric. If it isn't? Let me know, we have a
    bug. :-)</para>

    <bridgehead>Stickiness</bridgehead>

    <para>Is calculated as 1 - (Single Access / Entry Page Views) expressed as
    a percentage. In essence Stickiness describes how useful a given entry
    page is to draw Visitors deeper into your site. The stickier the page, the
    more folk are caught by it. :-) The closer to 100% the better. Generally.
    Certain pages within YOUR website may not make sense to have a high
    stickiness or even &gt; 5%. This measurement is a clue to understanding
    how your site is used, it is not a rule. How is this useful? How and where
    are people entering your web site. Does that make sense? Should it be here
    or there? What can you change to fix this and hence improve their use of
    your website.</para>

    <bridgehead>Popularity</bridgehead>

    <para>Popularity is the Ratio of Page Entries to Page Exits. o If it
    equals 1.0? Then the number of visitors to your site who started with that
    page, equals the number who left at that page. o If greater then 1.0, then
    more people entered here then left. o If less then 0? More people left
    from here then entered. I personally find this metric one of the more
    useful "At a Glance: How are Pages Performing" metrics. One of the
    difficulties with using this particular metric is that certain numbers
    will NOT make sense for YOUR site. In that a natural exit page would
    expect to have a very low Popularity. It's an exit page, not an entry
    page. So if an exit page has a high popularity, then you have a real
    problem. Likewise, a low Popularity for an entry page is unlikely to be a
    Good Thing(tm).</para>

    <para>"Where &amp; Why?" All three of these metrics are covered very
    nicely in Hack #58 from "Web Site Measurement Hacks" [1]. Which is where,
    credit where credit due, the inspiration to add these metrics came
    from.</para>
  </refsect1>

  <refsect1 id="running_awffull">
    <title>Running AWFFull</title>

    <para><application><productname>AWFFull</productname></application> is
    designed to be run from a Unix command line prompt or as a crond(8) job.
    There is no need to run with super-user privleges, and indeed, is
    preferable NOT to.</para>

    <para>Once executed, the general flow of the program is:</para>

    <procedure>
      <step>
        <para>A default configuration file is scanned for,
        <filename>/usr/local/etc/awffull.conf</filename> and, if found, is
        used.</para>
      </step>

      <step>
        <para>Any command line arguments given to the program are parsed. This
        may include the specification of one or more configuration files,
        which are processed at the time it is encountered.</para>

        <para>It can be useful to have multiple config files. A master used
        for multiple sites, and individualised config files. Do be aware that
        last option set wins. So last config file, or if after a config file,
        command line options. Useful if you desire to send the output to an
        alternate directory.</para>
      </step>

      <step>
        <para>If a log file was specified, it is opened and made ready for
        processing. If no log file was given, STDIN is used for input. If the
        log filename '-' is specified, STDIN will be forced.</para>
      </step>

      <step>
        <para>If an output directory was specified,
        <productname>AWFFull</productname> changes to that directory in
        preparation for generating output. If no output directory was given,
        the current directory is used.</para>
      </step>

      <step>
        <para>If no hostname was given, the program attempts to get the
        hostname using a <productname>uname</productname>(2) system call. If
        that fails, localhost is used.</para>
      </step>

      <step>
        <para>A history file is searched for in the current directory (output
        directory) and read if found. This file keeps totals for previous
        months, which is used in the main index.html HTML document. Note: The
        file location can now be specified with the HistoryName configuration
        option.</para>
      </step>

      <step>
        <para>If incremental processing was specified, a data file is searched
        for and loaded if found, containing the 'internal state' data of the
        program at the end of a previous run. Note: The file location can now
        be specified with the IncrementalName configuration option.</para>
      </step>

      <step>
        <para>Main processing begins on the log file. If the log spans
        multiple months, a separate HTML document is created for each month.
        After main processing, the main index.html page is created, which has
        totals by month and links to each months HTML document.</para>
      </step>

      <step>
        <para>A new history file is saved to disk, which includes totals
        generated by <productname>AWFFull</productname> during the current
        run.</para>
      </step>

      <step>
        <para>If incremental processing was specified, a data file is written
        that contains the 'internal state' data at the end of this run.</para>
      </step>
    </procedure>
  </refsect1>

  <refsect1 id="incremental_processing">
    <title>Incremental Processing</title>

    <para>Version 1.2x of <productname><application>The
    Webalizer</application></productname> added incremental run capability.
    Simply put, this allows processing large log files by breaking them up
    into smaller pieces, and processing these pieces instead. What this means
    in real terms is that you can now rotate your log files as often as you
    want, and still be able to produce monthly usage statistics without the
    loss of any detail. Basically, <productname>AWFFull</productname> saves
    and restores all internal data in a file named
    <filename><application>awffull.current</application></filename>. This
    allows the program to 'start where it left off' so to speak, and allows
    the preservation of detail from one run to the next. The data file is
    placed in the current output directory, and is a plain ASCII text file
    that can be viewed with any standard text editor. It's location and name
    may be changed using the <application>IncrementalName</application>
    configuration keyword.</para>

    <para>Some special precautions need to be taken when using the incremental
    run capability of <productname>AWFFull</productname>. Configuration
    options should not be changed between runs, as that could cause corruption
    of the internal data stored. For example, changing the
    <application>MangleAgents</application> level will cause different
    representations of user agents to be stored, producing invalid results in
    the user agents section of the report. If you need to change configuration
    options, do it at the end of the month after normal processing of the
    previous month and before processing the current month. You may also want
    to delete the <application>awffull.current</application> file as
    well.</para>

    <para><application><productname>AWFFull</productname></application> also
    attempts to prevent data duplication by keeping track of the timestamp of
    the last record processed. This timestamp is then compared to current
    records being processed, and any records that were logged previous to that
    timestamp are ignored. This, in theory, should allow you to re-process
    logs that have already been processed, or process logs that contain a mix
    of processed/not yet processed records, and not produce duplication of
    statistics.</para>

    <para>The only time this may break is if you have duplicate timestamps in
    two separate log files. Any records in the second log file that do have
    the same timestamp as the last record in the previous log file processed,
    will be discarded as if they had already been processed. There are lots of
    ways to prevent this however, for example, stopping the web server before
    rotating logs will prevent this situation, or using a tool such as
    cronolog (<ulink url="http://cronolog.org/">http://cronolog.org/</ulink>).
    This setup also necessitates that you always process logs in chronological
    order, otherwise data loss will occur as a result of the timestamp
    compare.</para>
  </refsect1>

  <refsect1 id="reverse_dns_lookups">
    <title>Reverse DNS Lookups</title>

    <para><application><productname>AWFFull</productname></application> no
    longer supports DNS lookups. Please use an external program such as
    <productname>DNShistory</productname> or
    <productname>DNSTran</productname> instead.</para>

    <itemizedlist>
      <listitem>
        <para><ulink
        url="http://www.summary.net/soft/dnstran.html">http://www.summary.net/soft/dnstran.html</ulink></para>
      </listitem>

      <listitem>
        <para><ulink
        url="http://www.stedee.id.au/dnshistory">http://www.stedee.id.au/dnshistory</ulink></para>
      </listitem>
    </itemizedlist>

    <para>With version 3.7.1 of <productname>AWFFull</productname>,
    <productname>GeoIP</productname> capability can be used for improved
    country detection.</para>
  </refsect1>

  <refsect1 id="command_line_options">
    <title>Command Line Options</title>

    <para><productname>AWFFull</productname> supports many different
    configuration options that will alter the way the program behaves and
    generates output. Most of these can be specified on the command line,
    while some can only be specified in a configuration file. The command line
    options are listed below, with references to the corresponding
    configuration file keywords. See also awffull.conf(5).</para>

    <bridgehead>General Options</bridgehead>

    <variablelist>
      <varlistentry>
        <term><option>-h</option>, <option>--help</option></term>

        <listitem>
          <para>Display all available command line options and exit
          program</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-V</option>, <option>--version</option></term>

        <listitem>
          <para>Display program version and exit program</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-v --verbose</term>

        <listitem>
          <para><option>Verbosity</option> Display debugging information for
          errors and warnings. Multiple v's will increase the amount of
          information displayed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>--match_counts</term>

        <listitem>
          <para>Display optimisation useful information pertaining to the
          number of matches against various Group, Hide and Ignore
          options.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-i --ignore_history</term>

        <listitem>
          <para><option>IgnoreHist</option> Ignore history. USE WITH CAUTION.
          This will cause <productname>AWFFull</productname> to ignore any
          previous monthly history file only. Incremental data (if present) is
          still processed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-p --preserve_state</term>

        <listitem>
          <para><option>Incremental</option> Preserve internal data between
          runs.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-T --timing</term>

        <listitem>
          <para><option>TimeMe</option>. Force display of timing information
          at end of processing.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-c --config=FILE</term>

        <listitem>
          <para>Use configuration file <application>FILE</application></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-n NAME</term>

        <listitem>
          <para><option>HostName</option>. Use the hostname
          <application>NAME</application>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-o --output=DIR</term>

        <listitem>
          <para><option>OutputDir</option>. Use output directory
          <application>DIR</application>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-t NAME</term>

        <listitem>
          <para><option>ReportTitle</option>. Use
          <application>NAME</application> for report title.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>F --logtype=TYPE</term>

        <listitem>
          <para><option>LogType</option>. Specify log type to be processed.
          Value can be one of: <application>auto</application>,
          <application>clf</application>, <application>combined</application>,
          <application>domino</application>, <application>ftp</application> or
          <application>squid</application> format. If not specified, will
          default to auto format. <application>FTP</application> logs must be
          in standard wu-ftpd <application>xferlog</application> format. A
          value of <quote>auto</quote> states that the log format
          automatically ascertained.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-f --fold</term>

        <listitem>
          <para><option>FoldSeqErr</option>. Fold out of sequence log records
          back into analysis, by treating as if they were the same date/time
          as the last good record. Normally, out of sequence log records are
          simply ignored.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-Y</term>

        <listitem>
          <para><option>CountryGraph</option>. Suppress country graph.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-G</term>

        <listitem>
          <para><option>HourlyGraph</option>. Suppress hourly graph.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-x NAME</term>

        <listitem>
          <para><option>HTMLExtension</option>. Defines the HTML file
          extension to use on the created report files. If not specified,
          defaults to <application>html</application>. Do not include the
          leading period.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-H</term>

        <listitem>
          <para><option>HourlyStats</option>. Suppress hourly
          statistics.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-L</term>

        <listitem>
          <para><option>GraphLegend</option>. Suppress color coded graph
          legends.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-l NUM</term>

        <listitem>
          <para><option>GraphLines</option>. Use background lines. The number
          of lines and where to place are automatically calculated. For
          backwards compatibility, any number &gt; 0 enables. Use zero ('0')
          to disable the lines.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-P NAME"</term>

        <listitem>
          <para><option>PageType</option>. Specify file extensions that are
          considered <application>pages</application>. Sometimes referred to
          as <application>pageviews</application>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-m NUM</term>

        <listitem>
          <para><option>VisitTimeout</option>. Specify the Visit timeout
          period. Specified in number of seconds. Default is 1800 seconds (30
          minutes). Sometimes referred to as
          <application>sessions</application>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-I NAME</term>

        <listitem>
          <para><option>IndexAlias</option>. Use the filename
          <application>name</application> as an additional alias for
          <application>index.</application></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-M NUM</term>

        <listitem>
          <para><option>MangleAgents</option>. Mangle user agent names
          according to the mangle level specified by
          <application>num</application>.</para>

          <para>Mangle levels are:</para>

          <para>5 - Browser name and major version</para>

          <para>4 - Browser name, major and minor version</para>

          <para>3 - Browser name, major version, minor version to two decimal
          places</para>

          <para>2 - Browser name, major and minor versions and
          sub-version</para>

          <para>1 - Browser name, version and machine type if possible</para>

          <para>0 - All information (left unchanged).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-g NUM</term>

        <listitem>
          <para>GroupDomains. Automatically group sites by domain. The
          grouping level specified by <application>num</application> can be
          thought of as 'the number of dots' to display in the grouping. The
          default value of 0 disables any domain grouping.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <bridgehead>Hide Options</bridgehead>

    <variablelist>
      <varlistentry>
        <term>-a NAME</term>

        <listitem>
          <para><option>HideAgent</option>. Hide user agents matching
          <application>name</application>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-r NAME</term>

        <listitem>
          <para><option>HideReferrer</option>. Hide referrer matching
          <application>name</application>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-s NAME</term>

        <listitem>
          <para><option>HideSite</option>. Hide site matching
          <application>name</application>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-X NAME</term>

        <listitem>
          <para><option>HideAllSites</option>. Hide all individual sites (only
          display groups).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-u NAME</term>

        <listitem>
          <para><option>HideURL</option>. Hide URL matching
          <application>name</application>.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <bridgehead>Table size options</bridgehead>

    <variablelist>
      <varlistentry>
        <term>-A --top_agents=NUM</term>

        <listitem>
          <para><option>TopAgents</option>. Display the top
          <application>num</application> user agents table.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-R --top_refers=NUM</term>

        <listitem>
          <para><option>TopReferrers</option>. Display the top
          <application>num</application> referrers table.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-S --top_sites=NUM</term>

        <listitem>
          <para><option>TopSites</option>. Display the top
          <application>num</application> sites table.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-U --top_urls=NUM</term>

        <listitem>
          <para><option>TopURLs</option>. Display the top
          <application>num</application> URL's table.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-C --top_countries=NUM</term>

        <listitem>
          <para><option>TopCountries</option>. Display the top
          <application>num</application> countries table.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-e --top_entry=NUM</term>

        <listitem>
          <para><option>TopEntry</option>. Display the top
          <application>num</application> entry pages table.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-E --top_exit=NUM</term>

        <listitem>
          <para><option>TopExit</option>. Display the top
          <application>num</application> exit pages table.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <bridgehead>Other Options</bridgehead>

    <variablelist>
      <varlistentry>
        <term>--use_geoip</term>

        <listitem>
          <para>Enables the use of the Maxmind GeoIP capability for more
          accurate detection of countries.</para>

          <para><emphasis>NOTE! Do not enable GeoIP if you analyse files that
          have had the IP Address translated to a Fully Qualified Host Name.
          Use either raw IP Addresses and GeoIP, or Names and disable GeoIP.
          ie. Don't use GeoIP AND DNShistory.</emphasis></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>--match_counts</term>

        <listitem>
          <para>Display the various Group/Hide etc Match Counts. This option
          is ideal for optimisation of the awffull.conf file. Just be careful
          with optimising Agents in particular, as the order is typically
          important.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="configuration_files">
    <title>Configuration Files</title>

    <para>See the <productname>awffull.conf</productname>(5) man page for
    complete details of all configuration options.</para>

    <para>Configuration files are standard <productname>ASCII</productname>(7)
    text files that may be created or edited using any standard editor.</para>

    <para>Blank lines and lines that begin with a pound sign ('#') are
    ignored.</para>

    <para>Any other lines are considered to be configuration lines, and have
    the form <quote>Keyword Value</quote>, where the <quote>Keyword</quote> is
    one of the currently available configuration keywords (see
    <productname>awffull.conf</productname>(5)), and <quote>Value</quote> is
    the value to assign to that particular option.</para>

    <para>Any text found after the keyword up to the end of the line is
    considered the keyword's value, so you should not include anything after
    the actual value on the line that is not actually part of the value being
    assigned. The file
    <filename><application>sample.conf</application></filename> provided with
    the distribution contains lots of useful documentation and examples as
    well.</para>

    <para>Certain "Keywords" will accept a 2nd value. In those situations, the
    first value may be enclosed in double quotes (") to allow for
    whitespace.</para>
  </refsect1>

  <refsect1 id="see_also">
    <title>See Also</title>

    <para><productname>awffull.conf</productname>(5)</para>
  </refsect1>

  <refsect1 id="bugs">
    <title>Bugs</title>

    <para>None currently known. YMMV....</para>

    <para>Report bugs to <ulink
    url="https://bugs.launchpad.net/awffull">https://bugs.launchpad.net/awffull</ulink>,
    or use the email discussion list:
    <email>awffull@stedee.id.au</email></para>
  </refsect1>

  <refsect1 id="notes">
    <title>Notes</title>

    <para>In case it is not obvious: AWFFull is a play/pun on the word
    <quote>awful</quote>, and is pronounced the same way. Yes it was
    deliberate.</para>
  </refsect1>

  <refsect1 id="references">
    <title>References</title>

    <para>[1] Web Site Measurement Hacks. Eric T. Peterson (and others).
    O'Reilly. ISBN 0-596-00988-7.</para>

    <para></para>
  </refsect1>
</refentry>