<!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>btcompletedir.bittornado</refentrytitle>">
  <!ENTITY dhpackage   "btcompletedir">

  <!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>creates torrent meta-info files for all files/directories within a directory</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>

      <arg choice="req"> <replaceable>trackerURL</replaceable></arg>
      <arg choice="req"><replaceable>directory</replaceable></arg>
      <arg rep="Repeat"><replaceable>directory</replaceable></arg>
      <arg><option>--piece_size_pow2 <replaceable>num</replaceable></option></arg>
      <arg><option>--comment <replaceable>comment</replaceable></option></arg>
      <arg><option>--filesystem_encoding <replaceable>encoding</replaceable></option></arg>
      <arg><option>--httpseeds <replaceable>seedURLlist</replaceable></option></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 that is used to generate the torrent info files
      that are distributed to bittorrent clients (usually over http) to inform them
      of where the designated tracker for the torrent is located, and to enable them
      to verify the file's contents.</para>

    <para><command>&dhpackage;</command> requires two arguments. The first is the <replaceable>trackerURL</replaceable> which is the
      "announce" address of a tracker (ex. http://127.0.0.1:6969/announce), the second is the
      <replaceable>directory</replaceable> that you wish to parse to generate torrent info files.</para>

    <para><command>&dhpackage;</command> will parse each <replaceable>directory</replaceable> given and create a torrent file for every file and directory
      within it. All torrent files will also reside in the <replaceable>directory</replaceable> after the program is complete.</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>--piece_size_pow2 <replaceable>num</replaceable></option></term>
        <listitem>
          <para>set the piece size to this power of 2 (0 = automatic) (defaults
	    to 0)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--comment <replaceable>comment</replaceable></option></term>
        <listitem>
          <para>optional human-readable <replaceable>comment</replaceable> to put in the torrent file (defaults to '')</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--filesystem_encoding <replaceable>encoding</replaceable></option></term>
        <listitem>
          <para>an optional <replaceable>encoding</replaceable> specification for the filesystem (set automatically in
	    recent Python versions) (defaults to '')</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--httpseeds <replaceable>seedURLlist</replaceable></option></term>
        <listitem>
          <para>a list of http seed URLs. These alternate URLs will be used to seed
	    the file if there are no other seeds available. The format of <replaceable>seedURLlist</replaceable> is as follows:</para>

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

	  <para>(defaults to '')</para>
        </listitem>
      </varlistentry>
      <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>directory</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>directory</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>directory</replaceable>	--announce_list http://track1.com|http://track2.com,http://track3.com</programlisting>
    </informalexample>

  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <citerefentry><refentrytitle>btcompletedirgui</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btmakemetafile</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>btmaketorrentgui</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:
-->
