<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Cameron</firstname>">
  <!ENTITY dhsurname   "<surname>Dale</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>April 17, 2005</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>camrdale@gmail.com</email>">
  <!ENTITY dhusername  "Cameron Dale">
  <!ENTITY dhucpackage "<refentrytitle>btreannounce.bittornado</refentrytitle>">
  <!ENTITY dhpackage   "btreannounce">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2006</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>

  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>change the announce address of a torrent file</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>

      <arg choice="req"> <replaceable>trackerURL</replaceable></arg>
      <arg choice="req"><replaceable>file</replaceable></arg>
      <arg rep="Repeat"><replaceable>file</replaceable></arg>
      <arg><option>--announce_list <replaceable>announceURLlist</replaceable></option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>This manual page documents briefly the
      <command>&dhpackage;</command> command.</para>

    <para>This manual page was written for the &debian; distribution
      because the original program does not have a manual page.</para>

    <para><command>&dhpackage;</command> is a program which will change the announce 
      address of a existing torrent file. The already existing torrent specified by 
      the <replaceable>file</replaceable> argument will be modified to use the new 
      announce url given by the <replaceable>trackerURL</replaceable> argument.</para>

  </refsect1>

  <refsect1>
    <title>OPTIONS</title>

    <para>These programs follow the usual &gnu; command line syntax,
      with long options starting with two dashes (`--').  A summary of
      options is included below.</para>

    <variablelist>
      <varlistentry>
        <term><option>--announce_list <replaceable>announceURLlist</replaceable></option></term>
        <listitem>
          <para>a list of announce URLs. This is an optional list
            of redundant/backup tracker URLs. The format of <replaceable>announceURLlist</replaceable> is as follows:</para>

          <para><replaceable>URL</replaceable>[,<replaceable>URL</replaceable> ...][|<replaceable>URL</replaceable>[,<replaceable>URL</replaceable> ...] ...]</para>

          <para>where the URLs separated by commas are tried randomly, then the
            groups of URLs separated by pipes are tried in sequential order.
            If this option is omitted, it is assumed you don't want an announce_list field in the metafile.
            If announce_list is given, clients which support it
            will ignore the <replaceable>trackerURL</replaceable> value. (defaults to '')</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>EXAMPLES</title>

    <para>These examples show how to use the --announce_list option in a few scenarios.</para>

    <para>Try the three trackers (1-3) in sequential order:</para>

    <informalexample>
      <programlisting><command>&dhpackage;</command> <replaceable>trackerURL</replaceable> <replaceable>file</replaceable> --announce_list http://track1.com|http://track2.com|http://track3.com</programlisting>
    </informalexample>

    <para>Try the three trackers (1-3) in a randomly selected order:</para>

    <informalexample>
      <programlisting><command>&dhpackage;</command> <replaceable>trackerURL</replaceable> <replaceable>file</replaceable> --announce_list http://track1.com,http://track2.com,http://track3.com</programlisting>
    </informalexample>
    
    <para>Try the main tracker (1) first, then try the two backups (2 and 3) randomly:</para>

    <informalexample>
      <programlisting><command>&dhpackage;</command> <replaceable>trackerURL</replaceable> <replaceable>file</replaceable> --announce_list http://track1.com|http://track2.com,http://track3.com</programlisting>
    </informalexample>

  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry><refentrytitle>btcopyannounce</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btrename</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btsethttpseeds</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btshowmetainfo</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>bittorrent-downloader</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
    </para>
  </refsect1>
  <refsect1>
    <title>AUTHOR</title>
    <para>This manual page was written by &dhusername; &lt;&dhemail;> (based on the original man pages written by Micah Anderson &lt;micah@debian.org>) for
      the &debian; system (but may be used by others).  Permission is
      granted to copy, distribute and/or modify this document under
      the terms of the &gnu; General Public License, Version 2 or any
      later version published by the Free Software Foundation.
    </para>
    <para>
      On Debian systems, the complete text of the GNU General Public
      License can be found in /usr/share/common-licenses/GPL.
    </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:
-->
