<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
  <!ENTITY debian  "<productname>Debian GNU/Linux</productname>">
  <!ENTITY docbook "<productname>DocBook</productname>">
  <!ENTITY sgml    "<abbrev>SGML</abbrev>">
]>

<!-- Manual page for aubconf, DocBook source file
     (C) 2002 Mako Hill <mako@debian.org>     -->

<refentry>
  <refentryinfo>
    <address>
      <email>mako@debian.org</email>
    </address>
    <author>
      <firstname>Benjamin</firstname>
      <surname>Hill</surname>
      <othername>Mako</othername>
    </author>
    <date>2002-03-10</date>
  </refentryinfo>
  <refmeta>
    <refentrytitle>aubconf</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>aubconf</refname> 
    <refpurpose>Configuration file for aub</refpurpose>
  </refnamediv><refsect1>
    <title>DESCRIPTION</title>

    <para>The vast majority of aub configuration is done in the
      <filename>aubconf</filename> configuration file.</para>

    <para>Configuration files are line-oriented; each line is
      processed separately.  If any line contains the '#' character
      that is not escaped with a '\', aub concludes that the character
      begins a comment, and discards the comment character and
      everything on the line that follows it.</para>

    <para>Each non-blank line in a configuration file must begin with
      a keyword recognized by aub.  The case of keywords is not
      significant.  As far as aub is concerned, "keyword", "KEYWORD",
      "Keyword" and "KeYWorD" all mean the same thing.  Some keywords
      require arguments; some require no arguments appear, and some
      permit variable numbers of arguments.  If aub sees keywords it
      doesn't understand in your aubconf file, it will complain to you
      about them.</para>

  </refsect1>

  <refsect1>
    <title>COMMANDS</title> 

    <para>Commands are treated as either position sensitive or
      position insensitive. When a position sensitive keyword appears
      <emphasis>before</emphasis> any GROUP keyword, the keyword is
      interpreted as being the default for all groups that appear
      later. When a position sensitive keyword appears
      <emphasis>after</emphasis> any GROUP keyword, it is interpreting
      as applying <emphasis>only</emphasis> to that group, overriding
      any previous default which may have been established via use of
      the same keyword, or by the value of environment
      variables.</para>

    <para>Position sensitive keywords appearing after a GROUP keyword
      which lists multiple groups are applied only to the last group
      listed, not to all groups appearing on the group line.</para>

    <para>Position sensitive keywords will be marked in the list of all
      commands below:</para>

    <variablelist>
      <varlistentry>
	<term><command>GROUP</command> <replaceable>newsgroup ...</replaceable></term>
	<listitem>
	  <para>Name of the Usenet group (or groups) that you want aub
	    to process.</para>

	  <para>Every configuration file must contain at least one
	    GROUP keyword to be correct.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>DIR, directory</command> <replaceable>directory</replaceable></term>
	<listitem>
	  <para>This keyword is used to tell aub what directory to put
	    binaries it decodes in. It is position sensitive.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>DESC, description</command> <replaceable>file</replaceable></term>
	<listitem>
	  <para>This keyword causes aub to extract text from what it
	    thinks is the text portion of posted articles, and append
	    it to the file you specify.  This is useful if you're
	    interested in reading the text that describes what all the
	    binaries aub is unpacking are about. It is position
	    sensitive.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>HOOK</command> <replaceable>program</replaceable></term>
	<listitem>
	  <para>This keyword enables you to select which binaries aub
	    decodes using your own software.  If the HOOK keyword is
	    specified, aub will invoke the argument program and supply
	    it with subject line of the first piece of a binary that
	    it can potentially decode via standard input.  If the
	    program returns true (zero), aub will decode the binary.
	    If the program returns false (non-zero), aub will skip
	    decoding the binary, and continue processing. It is
	    position sensitive.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>POST, postprocess</command> <replaceable>postprocessor</replaceable> <replaceable>extension</replaceable></term>
	<listitem>
	  <para>This keyword enables you to postprocess binaries whose
	    names end in the string <replaceable>extension</replaceable> (you
	    can list any number of these suffixes on a single line in
	    the configuration file).  Before a POSTprocess keyword can
	    appear, <replaceable>postprocessor</replaceable> must first be
	    defined using the DEFine keyword. This keyword is position
	    sensitive. </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>DEF, define</command> <replaceable>postprocessor</replaceable> <replaceable>UNIX command</replaceable></term>
	<listitem>
	  <para>This keyword lets you define a
	    postprocessor. <replaceable>UNIX command</replaceable> is any UNIX
	    command, with arguments.  Simple substitutions are
	    performed on <replaceable>UNIX command</replaceable> before it's
	    executed in conjunction with the existence of a
	    POSTprocess keyword and the appearance of a binary whose
	    filename ends in one of the <replaceable>extension</replaceable>
	    suffixes listed as arguments to the POSTprocess
	    keyword. This can be confusing and there are useful
	    examples in the main documentation. This keyword is
	    position insensitive.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>NNTP</command> <replaceable>news server</replaceable></term>
	<listitem>
	  <para>This tells aub that your news access is NNTP-based,
	    and that it should use the specified host as an NNTP
	    server. If you don't include this line, aub will try to
	    use the <envar>NNTPSERVER</envar> environment
	    variable. This keyword is position insensitive.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>SPOOL</command> <replaceable>directory</replaceable></term>
	<listitem>
	  <para>This tells aub that your news access is based on
	    access to raw news files, and that
	    <replaceable>directory</replaceable> is the root of the news spool
	    tree. A single configuration file may not contain both the
	    NNTP and SPOOL keywords. This keyword is position
	    insensitive.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>DEBUG</command> <replaceable>N</replaceable></term>
	<listitem>
	  <para>Sets the default debugging level aub runs at to N.  N
	    must be a non-negative integer.  Debugging level 0 is the
	    default; when run at debugging level zero, aub produces no
	    output unless it runs into serious problems.  Setting the
	    debugging level to 1 will tell you about what aub is
	    doing.  Setting the debugging level to 2 will tell you
	    even more about what aub is doing.  Setting the debugging
	    level to 3 or higher will show you more than you ever
	    wanted to know. This keyword is position
	    insensitive. </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>REC, recognize</command> <replaceable>extension</replaceable></term>
	<listitem>
	  <para>The recognition code (the part of aub that identifies
	    binaries) maintains a list of common suffixes that it uses
	    to recognize binaries while it scans subject lines. The
	    RECognize keyword allows you to add suffixes to this
	    internal list of hints.This keyword is position
	    insensitive.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>ONLYREC, onlyrecognize</command> <replaceable>extension</replaceable></term>
	<listitem>
	  <para>Works like RECognize, except that this list will not
	    add to, but will replace the current list of extensions,
	    and aub will only extract files that match one of the
	    given extensions. This keyword is position
	    insensitive.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>SAM, sample</command> <replaceable>N</replaceable></term>
	<listitem>
	  <para>For each group, examine at most
	    <replaceable>N</replaceable> messages. Note that fewer
	    than <replaceable>N</replaceable> messages may be loaded,
	    if the newsgroup is missing articles.This keyword is
	    position insensitive. </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>NOXHDR</command></term>
	<listitem>
	  <para>This keyword is meaningful only if your news access is
	    NNTP-based.  It will cause aub to not use the XHDR command
	    to access the subject lines of news articles, even if the
	    NNTP server you're using has XHDR capability. This keyword
	    is position insensitive.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><command>USER</command> <replaceable>username</replaceable></term>
	<listitem>
	  <para>This keyword is meaningful only if your news access is
	    NNTP-based. It enables NNTP authentication and provides
	    the name you will use to log in. This keyword is position
	    insensitive.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><cmdsynopsis><command>PASS</command><arg><replaceable>password</replaceable></arg></cmdsynopsis></term>
	<listitem>
	  <para>This keyword is meaningful only if your news access is
	    NNTP-based. It enables NNTP authentication and provides
	    the name you will use to log in. This keyword is position
	    insensitive.</para>
	</listitem>
      </varlistentry>


      <varlistentry>
	<term><cmdsynopsis><command>SKIPunresolved</command></cmdsynopsis></term>
	<listitem>
	  <para>This keyword will have aub completely ignore any
	    unresolved articles. On large groups, this can be a huge
	    speed-up but it will also result in aub ignoring any file
	    that is incomplete as of the time you run aub but may
	    complete itself later. Be careful when you use this as it
	    will update the .aubrc file as if they had all be checked
	    and come negatively. In other words, you run this once and
	    any information you have about unresolved articles
	    previous to running this is thrown away. Using this
	    keyword is not recommended but it's here per a user
	    request.</para>
	</listitem>
      </varlistentry>


    </variablelist>

    <para>If the same keyword appears multiple times, and the second
      appearance is not a position sensitive override of some
      established default, then aub ignores the second instance of the
      keyword. </para>

  </refsect1>

  <refsect1>
    <title>EXAMPLES</title>

    <screen>NNTP my.news.server
# optional: sample
SAMPLE 1000

# optional: onlyrecognize - saves files only if they have these extensions
# case-insensitive (.gif matches .GIF too, files will be saved as .gif)
ONLYRECOGNIZE .gif .jpg .jpeg .mpg .mpeg .mp3

# default directory to extract all files to
DIR /var/cache/aub/incoming/food

# add as many "group" directives as needed....
# group may be followed by another "dir" which applies to that group only
GROUP alt.binaries.food
GROUP alt.binaries.food.sushi
</screen>

  </refsect1>

  <refsect1>
    <title>AUTHORS</title>

    <para>Mark Stantz (No valid email address known)</para>
    <para>Brandon Long <email>blong@fiction.net</email></para>
    <para>Avinash Chopde <email>avinash@acm.org</email></para>
    <para>Mako Hill <email>mako@debian.org</email> (responsible for
      this document)</para>

  </refsect1>

  <refsect1>
    <title>COPYRIGHT</title>

    <para>Copyright (c) 1992-2002 Mark Stantz, Brandon Long, Avinash
    Chopde, Mako Hill</para>

    <para>This code is offered as-is.  Anyone is welcome to make
      improvements, provided that my notice of authorship is retained.
      I accept no responsibility for loss or damage caused by this
      program, nor do I accept responsibility for supporting
      it.</para>

  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>

    <para><filename>aub(1)</filename>; the
      <filename>INTRODUCING_AUB</filename> document</para>
  </refsect1>


</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->