Clean up the language in the description and man pages.
authorCameron Dale <camrdale@gmail.com>
Sat, 26 Apr 2008 01:24:50 +0000 (18:24 -0700)
committerCameron Dale <camrdale@gmail.com>
Sat, 26 Apr 2008 01:24:50 +0000 (18:24 -0700)
Also tightened the dependency on Twisted to 8.0.

debian/apt-p2p.conf.sgml
debian/apt-p2p.sgml
debian/control

index 21b9d3d..98a8a8c 100644 (file)
@@ -4,14 +4,14 @@
   <!ENTITY dhfirstname "<firstname>Cameron</firstname>">
   <!ENTITY dhsurname   "<surname>Dale</surname>">
   <!-- Please adjust the date whenever revising the manpage. -->
-  <!ENTITY dhdate      "<date>February 17, 2008</date>">
+  <!ENTITY dhdate      "<date>April 25, 2008</date>">
   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
        allowed: see man(7), man(1). -->
   <!ENTITY dhsection   "<manvolnum>5</manvolnum>">
   <!ENTITY dhemail     "<email>camrdale@gmail.com</email>">
   <!ENTITY dhusername  "Cameron Dale">
   <!ENTITY dhucpackage "<refentrytitle>apt-p2p.conf</refentrytitle>">
-  <!ENTITY dhpackage   "apt-p2p">
+  <!ENTITY dhpackage   "apt-p2p.conf">
 
   <!ENTITY debian      "<productname>Debian</productname>">
   <!ENTITY gnu         "<acronym>GNU</acronym>">
     <title>FORMAT</title>
 
     <para>&dhpackage; has a structure similar to Microsoft Windows INI files.
-       The configuration file consists of sections, led by a ``[section]'' header and followed
-       by ``name = value'' or ``name: value'' entries, with continuations in the style of RFC 822
+       The configuration file consists of sections, led by a '[section]' header and followed
+       by 'name = value' or 'name: value' entries, with continuations in the style of RFC 822
        (values can span multiple lines by starting the subsequent lines with one or more spaces).
        Some values indicate times, in which case a suffix of 'd' for
        days, 'h' for hours, 'm' for minutes, and 's' for seconds can be used.
        Boolean values can be '1', 'yes', 'true', and 'on' to evaluate to True,
        or '0', 'no', 'false', and 'off' to evaluate to false.
        Note that leading whitespace is removed from values, and case is not important.
-       Lines beginning with "#" or ";" are ignored and may be used to provide comments.</para>
+       Lines beginning with '#' or ';' are ignored and may be used to provide comments.</para>
     
   </refsect1>
   <refsect1>
             <listitem>
              <para>The <replaceable>time</replaceable> after which to refresh DHT keys.
                  This should be a time slightly less than the DHT's KEY_EXPIRE value.
-                 (Default is 57 minutes.)</para>
+                 (Default is 2.5 hours.)</para>
            </listitem>
          </varlistentry>
          <varlistentry>
          <varlistentry>
            <term><option>DHT = <replaceable>string</replaceable></option></term>
             <listitem>
-             <para>The DHT implementation to use. It must be possile to do (in python)
-               ``from &lt;DHT&gt;.DHT import DHT'' to get a class that implements the IDHT interface.
-               There should also be a similarly named section below to specify the options for the DHT.
-               (Default is `apt_p2p_Khashmir')</para>
+             <para>The DHT implementation to use. It must be possile to do (in python) 'from
+               &lt;DHT&gt;.DHT import DHT' to get a class that implements the IDHT interface.
+               There should also be a similarly named section in the config file to specify
+               the options for the DHT. (Default is 'apt_p2p_Khashmir')</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><option>KEY_EXPIRE = <replaceable>time</replaceable></option></term>
             <listitem>
              <para>The <replaceable>time</replaceable> to wait before expiring unrefreshed keys.
-                 (Default is 1 hour.)</para>
+                 (Default is 3 hours.)</para>
            </listitem>
          </varlistentry>
          <varlistentry>
index aa106a8..d8e9597 100644 (file)
@@ -4,7 +4,7 @@
   <!ENTITY dhfirstname "<firstname>Cameron</firstname>">
   <!ENTITY dhsurname   "<surname>Dale</surname>">
   <!-- Please adjust the date whenever revising the manpage. -->
-  <!ENTITY dhdate      "<date>February 17, 2008</date>">
+  <!ENTITY dhdate      "<date>April 25, 2008</date>">
   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
        allowed: see man(7), man(1). -->
   <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
   <refsynopsisdiv>
     <para>Normally &dhpackage; is run from init.d using <command>twistd</command>, in which case no &dhpackage;
         options can be specified on the command-line, and all configuration variables are
-        read from the default config file locations of ${HOME}/.apt-p2p.conf and /etc/apt-p2p/apt-p2p.conf.
+        read from the default config file locations of ${HOME}/.apt-p2p/apt-p2p.conf and /etc/apt-p2p/apt-p2p.conf.
         The command is then:</para>
     <cmdsynopsis>
       <command>twistd</command> <arg choice="Req">-y /path/to/&dhpackage;</arg> <arg rep="Repeat"><option>twistd options</option></arg>
     </cmdsynopsis>
-    <para>For a detailed listing of the twistd options, see
+    <para>For a detailed listing of the <command>twistd</command> options, see
         <citerefentry><refentrytitle>twistd</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
-    <para>&dhpackage; can also be run without twistd by executing:</para>
+    <para>&dhpackage; can also be run without <command>twistd</command> by executing:</para>
     <cmdsynopsis>
       <command>&dhpackage;</command> <arg rep="Repeat"><option>options</option></arg>
     </cmdsynopsis>
   <refsect1>
     <title>DESCRIPTION</title>
 
-    <para>This manual page documents briefly the options available to the &dhpackage; command.</para>
 
     <para><command>&dhpackage;</command> is a helper for downloading Debian packages files with APT.
         It will download any needed files from other Apt-P2P peers in a
-        bittorrent-like manner, and so reduce the strain on the Debian mirrors.</para>
+        peer-to-peer manner, and so reduce the strain on the Debian mirrors.</para>
 
-    <para>In order for APT to send it's requests to &dhpackage;, the source.list entries must be modified to point to the
+      <refsect2>
+       <title>APT SETUP</title>
+
+    <para>In order for APT to send it's requests to &dhpackage;, the sources.list entries must be modified to point to the
         local &dhpackage; address. Unless you have changed the default port, then adding "localhost:9977/" to the beginning
         of each entry should be sufficient. For example, if your sources.list contains a line like this:</para>
-
-    <para>deb http://ftp.us.debian.org/debian etch main contrib non-free</para>
-
+        
+    <blockquote><para>deb http://ftp.us.debian.org/debian etch main contrib non-free</para></blockquote>
+    
     <para>then replace it with this:</para>
-
-    <para>deb http://localhost:9977/ftp.us.debian.org/debian etch main contrib non-free</para>
+        
+    <blockquote><para>deb http://localhost:9977/ftp.us.debian.org/debian etch main contrib non-free</para></blockquote>
+
+    <para>You can do the same with 'deb-src' lines as well, and &dhpackage;
+        will be used to download and share your source packages as well.</para>
+
+      </refsect2>
+      <refsect2>
+       <title>PORT FORWARDING</title>
+
+    <para>It is VERY important that Apt-P2P's ports be reachable by other peers.
+        This is needed both to share files with others, and to connect to
+        others through the DHT to find peers for files. If you aren't
+        accessible by others, you will not only not share anything, but your
+        performance during downloading will be affected.</para>
+
+    <para>Apt-P2P uses a default port of 9977, over both TCP and UDP, for it's
+        communication. You can change this port in the
+        /etc/apt-p2p/apt-p2p.conf file, and use different ports for TCP and
+        UDP, if desired. Whatever port you use, make sure to forward it
+        through your NAT or firewall to improve your performance and share
+        with others. Information on port forwarding can be found here:</para>
+
+    <para><ulink url="http://portforward.com/"></ulink></para>
     
-    <para>The port can be changed in the &dhpackage; config file in /etc/&dhpackage;/&dhpackage;.conf,
-        but it defaults to 9977.</para>
-  </refsect1>
+      </refsect2>
+   </refsect1>
   <refsect1>
     <title>OPTIONS</title>
 
     <para>These programs follow the usual &gnu; command line syntax,
-      with short options starting with a single dash (`-'),
-      and long options starting with two dashes (`--').
+      with short options starting with a single dash ('-'),
+      and long options starting with two dashes ('--').
       A summary of options is included below.</para>
     
     <variablelist>
         <term><option>-l <replaceable>filename</replaceable>,</option> <option>--logfile=<replaceable>filename</replaceable></option></term>
          <listitem>
           <para>the <replaceable>filename</replaceable> to print log messages to,
-              or `-' to log to standard output, if not specified then
+              or '-' to log to standard output, if not specified then
               /var/log/apt-p2p.log will be used</para>
         </listitem>
       </varlistentry>
index c16ad75..6473a61 100644 (file)
@@ -12,12 +12,12 @@ XS-Dm-Upload-Allowed: yes
 
 Package: apt-p2p
 Architecture: all
-Depends: ${python:Depends}, ${misc:Depends}, python-twisted-web2 (>= 0.2), adduser, python-debian (>= 0.1.4), python-apt (>= 0.6.20), python-pysqlite2 (>= 2.1)
+Depends: ${python:Depends}, ${misc:Depends}, python-twisted-web2 (>= 8.0), adduser, python-debian (>= 0.1.4), python-apt (>= 0.6.20), python-pysqlite2 (>= 2.1)
 Provides: python-apt-p2p, python-apt-p2p-khashmir
 Description: apt helper for peer-to-peer downloads of Debian packages
  Apt-P2P is a helper for downloading Debian packages files with APT.
  It will download any needed files from other Apt-P2P peers in a
bittorrent-like manner, and so reduce the strain on the Debian mirrors.
peer-to-peer manner, and so reduce the strain on the Debian mirrors.
  .
  The Apt-P2P daemon runs automatically on startup and listens for
  requests from APT for files, as well as maintaining membership in a
@@ -25,7 +25,7 @@ Description: apt helper for peer-to-peer downloads of Debian packages
  available (most files), peers that have the file are looked for in the
  DHT. The file can then be downloaded from them, using the uploading
  bandwidth of other peers while reducing the demand on the Debian mirror
- network. However, if a package cannot be found on any peers, Apt-P2P
+ network. However, if a package can not be found on any peers, Apt-P2P
  will fall back to downloading from a mirror to ensure all packages are
  downloaded. Once downloaded, the file is hash checked and added to the
  DHT so that other peers can download it without the mirror.