From 463eb47011c036b19c79bffc33d893f58894dd05 Mon Sep 17 00:00:00 2001
From: Arvid Norberg <arvid@libtorrent.org>
Date: Sat, 24 Nov 2007 20:48:51 +0000
Subject: [PATCH] updated documentation

---
 docs/manual.html | 392 ++++++++++++++++++++++++++++-------------------
 docs/manual.rst  |  30 ++--
 2 files changed, 258 insertions(+), 164 deletions(-)

diff --git a/docs/manual.html b/docs/manual.html
index d592caff8..f861a8787 100644
--- a/docs/manual.html
+++ b/docs/manual.html
@@ -25,172 +25,176 @@
 <p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
 <ul class="simple">
 <li><a class="reference" href="#overview" id="id18" name="id18">overview</a></li>
-<li><a class="reference" href="#primitive-network-types" id="id19" name="id19">primitive network types</a></li>
+<li><a class="reference" href="#network-primitives" id="id19" name="id19">network primitives</a></li>
 <li><a class="reference" href="#session" id="id20" name="id20">session</a><ul>
 <li><a class="reference" href="#id1" id="id21" name="id21">session()</a></li>
 <li><a class="reference" href="#id2" id="id22" name="id22">~session()</a></li>
 <li><a class="reference" href="#abort" id="id23" name="id23">abort()</a></li>
 <li><a class="reference" href="#add-torrent" id="id24" name="id24">add_torrent()</a></li>
-<li><a class="reference" href="#remove-torrent-find-torrent-get-torrents" id="id25" name="id25">remove_torrent() find_torrent() get_torrents()</a></li>
-<li><a class="reference" href="#set-upload-rate-limit-set-download-rate-limit-upload-rate-limit-download-rate-limit" id="id26" name="id26">set_upload_rate_limit() set_download_rate_limit() upload_rate_limit() download_rate_limit()</a></li>
-<li><a class="reference" href="#set-max-uploads-set-max-connections" id="id27" name="id27">set_max_uploads() set_max_connections()</a></li>
-<li><a class="reference" href="#num-uploads-num-connections" id="id28" name="id28">num_uploads() num_connections()</a></li>
-<li><a class="reference" href="#set-max-half-open-connections-max-half-open-connections" id="id29" name="id29">set_max_half_open_connections() max_half_open_connections()</a></li>
-<li><a class="reference" href="#set-ip-filter" id="id30" name="id30">set_ip_filter()</a></li>
-<li><a class="reference" href="#status" id="id31" name="id31">status()</a></li>
-<li><a class="reference" href="#is-listening-listen-port-listen-on" id="id32" name="id32">is_listening() listen_port() listen_on()</a></li>
-<li><a class="reference" href="#pop-alert-set-severity-level" id="id33" name="id33">pop_alert() set_severity_level()</a></li>
-<li><a class="reference" href="#add-extension" id="id34" name="id34">add_extension()</a></li>
-<li><a class="reference" href="#set-settings-set-pe-settings" id="id35" name="id35">set_settings() set_pe_settings()</a></li>
-<li><a class="reference" href="#set-peer-proxy-set-web-seed-proxy-set-tracker-proxy-set-dht-proxy" id="id36" name="id36">set_peer_proxy() set_web_seed_proxy() set_tracker_proxy() set_dht_proxy()</a></li>
-<li><a class="reference" href="#peer-proxy-web-seed-proxy-tracker-proxy-dht-proxy" id="id37" name="id37">peer_proxy() web_seed_proxy() tracker_proxy() dht_proxy()</a></li>
-<li><a class="reference" href="#start-dht-stop-dht-set-dht-settings-dht-state" id="id38" name="id38">start_dht() stop_dht() set_dht_settings() dht_state()</a></li>
-<li><a class="reference" href="#add-dht-node-add-dht-router" id="id39" name="id39">add_dht_node() add_dht_router()</a></li>
+<li><a class="reference" href="#remove-torrent" id="id25" name="id25">remove_torrent()</a></li>
+<li><a class="reference" href="#find-torrent-get-torrents" id="id26" name="id26">find_torrent() get_torrents()</a></li>
+<li><a class="reference" href="#set-upload-rate-limit-set-download-rate-limit-upload-rate-limit-download-rate-limit" id="id27" name="id27">set_upload_rate_limit() set_download_rate_limit() upload_rate_limit() download_rate_limit()</a></li>
+<li><a class="reference" href="#set-max-uploads-set-max-connections" id="id28" name="id28">set_max_uploads() set_max_connections()</a></li>
+<li><a class="reference" href="#num-uploads-num-connections" id="id29" name="id29">num_uploads() num_connections()</a></li>
+<li><a class="reference" href="#set-max-half-open-connections-max-half-open-connections" id="id30" name="id30">set_max_half_open_connections() max_half_open_connections()</a></li>
+<li><a class="reference" href="#set-ip-filter" id="id31" name="id31">set_ip_filter()</a></li>
+<li><a class="reference" href="#status" id="id32" name="id32">status()</a></li>
+<li><a class="reference" href="#is-listening-listen-port-listen-on" id="id33" name="id33">is_listening() listen_port() listen_on()</a></li>
+<li><a class="reference" href="#pop-alert-set-severity-level" id="id34" name="id34">pop_alert() set_severity_level()</a></li>
+<li><a class="reference" href="#add-extension" id="id35" name="id35">add_extension()</a></li>
+<li><a class="reference" href="#set-settings-set-pe-settings" id="id36" name="id36">set_settings() set_pe_settings()</a></li>
+<li><a class="reference" href="#set-peer-proxy-set-web-seed-proxy-set-tracker-proxy-set-dht-proxy" id="id37" name="id37">set_peer_proxy() set_web_seed_proxy() set_tracker_proxy() set_dht_proxy()</a></li>
+<li><a class="reference" href="#peer-proxy-web-seed-proxy-tracker-proxy-dht-proxy" id="id38" name="id38">peer_proxy() web_seed_proxy() tracker_proxy() dht_proxy()</a></li>
+<li><a class="reference" href="#start-dht-stop-dht-set-dht-settings-dht-state" id="id39" name="id39">start_dht() stop_dht() set_dht_settings() dht_state()</a></li>
+<li><a class="reference" href="#add-dht-node-add-dht-router" id="id40" name="id40">add_dht_node() add_dht_router()</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#entry" id="id40" name="id40">entry</a><ul>
-<li><a class="reference" href="#integer-string-list-dict-type" id="id41" name="id41">integer() string() list() dict() type()</a></li>
-<li><a class="reference" href="#operator" id="id42" name="id42">operator[]</a></li>
-<li><a class="reference" href="#find-key" id="id43" name="id43">find_key()</a></li>
+<li><a class="reference" href="#entry" id="id41" name="id41">entry</a><ul>
+<li><a class="reference" href="#integer-string-list-dict-type" id="id42" name="id42">integer() string() list() dict() type()</a></li>
+<li><a class="reference" href="#operator" id="id43" name="id43">operator[]</a></li>
+<li><a class="reference" href="#find-key" id="id44" name="id44">find_key()</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#torrent-info" id="id44" name="id44">torrent_info</a><ul>
-<li><a class="reference" href="#id3" id="id45" name="id45">torrent_info()</a></li>
-<li><a class="reference" href="#set-comment-set-piece-size-set-creator-set-hash-add-tracker-add-file" id="id46" name="id46">set_comment() set_piece_size() set_creator() set_hash() add_tracker() add_file()</a></li>
-<li><a class="reference" href="#create-torrent" id="id47" name="id47">create_torrent()</a></li>
-<li><a class="reference" href="#remap-files" id="id48" name="id48">remap_files()</a></li>
-<li><a class="reference" href="#begin-files-end-files-rbegin-files-rend-files" id="id49" name="id49">begin_files() end_files() rbegin_files() rend_files()</a></li>
-<li><a class="reference" href="#num-files-file-at" id="id50" name="id50">num_files() file_at()</a></li>
-<li><a class="reference" href="#map-block" id="id51" name="id51">map_block()</a></li>
-<li><a class="reference" href="#map-file" id="id52" name="id52">map_file()</a></li>
-<li><a class="reference" href="#url-seeds-add-url-seed" id="id53" name="id53">url_seeds() add_url_seed()</a></li>
-<li><a class="reference" href="#print" id="id54" name="id54">print()</a></li>
-<li><a class="reference" href="#trackers" id="id55" name="id55">trackers()</a></li>
-<li><a class="reference" href="#total-size-piece-length-piece-size-num-pieces" id="id56" name="id56">total_size() piece_length() piece_size() num_pieces()</a></li>
-<li><a class="reference" href="#hash-for-piece-info-hash" id="id57" name="id57">hash_for_piece() info_hash()</a></li>
-<li><a class="reference" href="#name-comment-creation-date-creator" id="id58" name="id58">name() comment() creation_date() creator()</a></li>
-<li><a class="reference" href="#priv-set-priv" id="id59" name="id59">priv() set_priv()</a></li>
-<li><a class="reference" href="#nodes" id="id60" name="id60">nodes()</a></li>
-<li><a class="reference" href="#add-node" id="id61" name="id61">add_node()</a></li>
+<li><a class="reference" href="#torrent-info" id="id45" name="id45">torrent_info</a><ul>
+<li><a class="reference" href="#id3" id="id46" name="id46">torrent_info()</a></li>
+<li><a class="reference" href="#set-comment-set-piece-size-set-creator-set-hash-add-tracker-add-file" id="id47" name="id47">set_comment() set_piece_size() set_creator() set_hash() add_tracker() add_file()</a></li>
+<li><a class="reference" href="#create-torrent" id="id48" name="id48">create_torrent()</a></li>
+<li><a class="reference" href="#remap-files" id="id49" name="id49">remap_files()</a></li>
+<li><a class="reference" href="#begin-files-end-files-rbegin-files-rend-files" id="id50" name="id50">begin_files() end_files() rbegin_files() rend_files()</a></li>
+<li><a class="reference" href="#num-files-file-at" id="id51" name="id51">num_files() file_at()</a></li>
+<li><a class="reference" href="#map-block" id="id52" name="id52">map_block()</a></li>
+<li><a class="reference" href="#map-file" id="id53" name="id53">map_file()</a></li>
+<li><a class="reference" href="#url-seeds-add-url-seed" id="id54" name="id54">url_seeds() add_url_seed()</a></li>
+<li><a class="reference" href="#print" id="id55" name="id55">print()</a></li>
+<li><a class="reference" href="#trackers" id="id56" name="id56">trackers()</a></li>
+<li><a class="reference" href="#total-size-piece-length-piece-size-num-pieces" id="id57" name="id57">total_size() piece_length() piece_size() num_pieces()</a></li>
+<li><a class="reference" href="#hash-for-piece-info-hash" id="id58" name="id58">hash_for_piece() info_hash()</a></li>
+<li><a class="reference" href="#name-comment-creation-date-creator" id="id59" name="id59">name() comment() creation_date() creator()</a></li>
+<li><a class="reference" href="#priv-set-priv" id="id60" name="id60">priv() set_priv()</a></li>
+<li><a class="reference" href="#nodes" id="id61" name="id61">nodes()</a></li>
+<li><a class="reference" href="#add-node" id="id62" name="id62">add_node()</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#torrent-handle" id="id62" name="id62">torrent_handle</a><ul>
-<li><a class="reference" href="#piece-priority-prioritize-pieces-piece-priorities-prioritize-files" id="id63" name="id63">piece_priority() prioritize_pieces() piece_priorities() prioritize_files()</a></li>
-<li><a class="reference" href="#file-progress" id="id64" name="id64">file_progress()</a></li>
-<li><a class="reference" href="#save-path" id="id65" name="id65">save_path()</a></li>
-<li><a class="reference" href="#move-storage" id="id66" name="id66">move_storage()</a></li>
-<li><a class="reference" href="#force-reannounce" id="id67" name="id67">force_reannounce()</a></li>
-<li><a class="reference" href="#connect-peer" id="id68" name="id68">connect_peer()</a></li>
-<li><a class="reference" href="#name" id="id69" name="id69">name()</a></li>
-<li><a class="reference" href="#set-ratio" id="id70" name="id70">set_ratio()</a></li>
-<li><a class="reference" href="#set-upload-limit-set-download-limit-upload-limit-download-limit" id="id71" name="id71">set_upload_limit() set_download_limit() upload_limit() download_limit()</a></li>
-<li><a class="reference" href="#set-sequenced-download-threshold" id="id72" name="id72">set_sequenced_download_threshold()</a></li>
-<li><a class="reference" href="#set-peer-upload-limit-set-peer-download-limit" id="id73" name="id73">set_peer_upload_limit() set_peer_download_limit()</a></li>
-<li><a class="reference" href="#pause-resume-is-paused" id="id74" name="id74">pause() resume() is_paused()</a></li>
-<li><a class="reference" href="#resolve-countries" id="id75" name="id75">resolve_countries()</a></li>
-<li><a class="reference" href="#is-seed" id="id76" name="id76">is_seed()</a></li>
-<li><a class="reference" href="#has-metadata" id="id77" name="id77">has_metadata()</a></li>
-<li><a class="reference" href="#set-tracker-login" id="id78" name="id78">set_tracker_login()</a></li>
-<li><a class="reference" href="#trackers-replace-trackers" id="id79" name="id79">trackers() replace_trackers()</a></li>
-<li><a class="reference" href="#add-url-seed-remove-url-seed-url-seeds" id="id80" name="id80">add_url_seed() remove_url_seed() url_seeds()</a></li>
-<li><a class="reference" href="#use-interface" id="id81" name="id81">use_interface()</a></li>
-<li><a class="reference" href="#info-hash" id="id82" name="id82">info_hash()</a></li>
-<li><a class="reference" href="#id5" id="id83" name="id83">set_max_uploads() set_max_connections()</a></li>
-<li><a class="reference" href="#write-resume-data" id="id84" name="id84">write_resume_data()</a></li>
-<li><a class="reference" href="#id6" id="id85" name="id85">status()</a></li>
-<li><a class="reference" href="#get-download-queue" id="id86" name="id86">get_download_queue()</a></li>
-<li><a class="reference" href="#get-peer-info" id="id87" name="id87">get_peer_info()</a></li>
-<li><a class="reference" href="#get-torrent-info" id="id88" name="id88">get_torrent_info()</a></li>
-<li><a class="reference" href="#is-valid" id="id89" name="id89">is_valid()</a></li>
+<li><a class="reference" href="#torrent-handle" id="id63" name="id63">torrent_handle</a><ul>
+<li><a class="reference" href="#piece-priority-prioritize-pieces-piece-priorities-prioritize-files" id="id64" name="id64">piece_priority() prioritize_pieces() piece_priorities() prioritize_files()</a></li>
+<li><a class="reference" href="#file-progress" id="id65" name="id65">file_progress()</a></li>
+<li><a class="reference" href="#save-path" id="id66" name="id66">save_path()</a></li>
+<li><a class="reference" href="#move-storage" id="id67" name="id67">move_storage()</a></li>
+<li><a class="reference" href="#force-reannounce" id="id68" name="id68">force_reannounce()</a></li>
+<li><a class="reference" href="#scrape-tracker" id="id69" name="id69">scrape_tracker()</a></li>
+<li><a class="reference" href="#connect-peer" id="id70" name="id70">connect_peer()</a></li>
+<li><a class="reference" href="#name" id="id71" name="id71">name()</a></li>
+<li><a class="reference" href="#set-ratio" id="id72" name="id72">set_ratio()</a></li>
+<li><a class="reference" href="#set-upload-limit-set-download-limit-upload-limit-download-limit" id="id73" name="id73">set_upload_limit() set_download_limit() upload_limit() download_limit()</a></li>
+<li><a class="reference" href="#set-sequenced-download-threshold" id="id74" name="id74">set_sequenced_download_threshold()</a></li>
+<li><a class="reference" href="#set-peer-upload-limit-set-peer-download-limit" id="id75" name="id75">set_peer_upload_limit() set_peer_download_limit()</a></li>
+<li><a class="reference" href="#pause-resume-is-paused" id="id76" name="id76">pause() resume() is_paused()</a></li>
+<li><a class="reference" href="#resolve-countries" id="id77" name="id77">resolve_countries()</a></li>
+<li><a class="reference" href="#is-seed" id="id78" name="id78">is_seed()</a></li>
+<li><a class="reference" href="#has-metadata" id="id79" name="id79">has_metadata()</a></li>
+<li><a class="reference" href="#set-tracker-login" id="id80" name="id80">set_tracker_login()</a></li>
+<li><a class="reference" href="#trackers-replace-trackers" id="id81" name="id81">trackers() replace_trackers()</a></li>
+<li><a class="reference" href="#add-url-seed-remove-url-seed-url-seeds" id="id82" name="id82">add_url_seed() remove_url_seed() url_seeds()</a></li>
+<li><a class="reference" href="#use-interface" id="id83" name="id83">use_interface()</a></li>
+<li><a class="reference" href="#info-hash" id="id84" name="id84">info_hash()</a></li>
+<li><a class="reference" href="#id5" id="id85" name="id85">set_max_uploads() set_max_connections()</a></li>
+<li><a class="reference" href="#write-resume-data" id="id86" name="id86">write_resume_data()</a></li>
+<li><a class="reference" href="#id6" id="id87" name="id87">status()</a></li>
+<li><a class="reference" href="#get-download-queue" id="id88" name="id88">get_download_queue()</a></li>
+<li><a class="reference" href="#get-peer-info" id="id89" name="id89">get_peer_info()</a></li>
+<li><a class="reference" href="#get-torrent-info" id="id90" name="id90">get_torrent_info()</a></li>
+<li><a class="reference" href="#is-valid" id="id91" name="id91">is_valid()</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#torrent-status" id="id90" name="id90">torrent_status</a></li>
-<li><a class="reference" href="#peer-info" id="id91" name="id91">peer_info</a></li>
-<li><a class="reference" href="#session-settings" id="id92" name="id92">session_settings</a></li>
-<li><a class="reference" href="#pe-settings" id="id93" name="id93">pe_settings</a></li>
-<li><a class="reference" href="#proxy-settings" id="id94" name="id94">proxy_settings</a></li>
-<li><a class="reference" href="#ip-filter" id="id95" name="id95">ip_filter</a><ul>
-<li><a class="reference" href="#id9" id="id96" name="id96">ip_filter()</a></li>
-<li><a class="reference" href="#add-rule" id="id97" name="id97">add_rule()</a></li>
-<li><a class="reference" href="#access" id="id98" name="id98">access()</a></li>
-<li><a class="reference" href="#export-filter" id="id99" name="id99">export_filter()</a></li>
+<li><a class="reference" href="#torrent-status" id="id92" name="id92">torrent_status</a></li>
+<li><a class="reference" href="#peer-info" id="id93" name="id93">peer_info</a></li>
+<li><a class="reference" href="#session-settings" id="id94" name="id94">session_settings</a></li>
+<li><a class="reference" href="#pe-settings" id="id95" name="id95">pe_settings</a></li>
+<li><a class="reference" href="#proxy-settings" id="id96" name="id96">proxy_settings</a></li>
+<li><a class="reference" href="#ip-filter" id="id97" name="id97">ip_filter</a><ul>
+<li><a class="reference" href="#id9" id="id98" name="id98">ip_filter()</a></li>
+<li><a class="reference" href="#add-rule" id="id99" name="id99">add_rule()</a></li>
+<li><a class="reference" href="#access" id="id100" name="id100">access()</a></li>
+<li><a class="reference" href="#export-filter" id="id101" name="id101">export_filter()</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#big-number" id="id100" name="id100">big_number</a></li>
-<li><a class="reference" href="#hasher" id="id101" name="id101">hasher</a></li>
-<li><a class="reference" href="#fingerprint" id="id102" name="id102">fingerprint</a></li>
-<li><a class="reference" href="#free-functions" id="id103" name="id103">free functions</a><ul>
-<li><a class="reference" href="#identify-client" id="id104" name="id104">identify_client()</a></li>
-<li><a class="reference" href="#client-fingerprint" id="id105" name="id105">client_fingerprint()</a></li>
-<li><a class="reference" href="#bdecode-bencode" id="id106" name="id106">bdecode() bencode()</a></li>
-<li><a class="reference" href="#supports-sparse-files" id="id107" name="id107">supports_sparse_files()</a></li>
+<li><a class="reference" href="#big-number" id="id102" name="id102">big_number</a></li>
+<li><a class="reference" href="#hasher" id="id103" name="id103">hasher</a></li>
+<li><a class="reference" href="#fingerprint" id="id104" name="id104">fingerprint</a></li>
+<li><a class="reference" href="#free-functions" id="id105" name="id105">free functions</a><ul>
+<li><a class="reference" href="#identify-client" id="id106" name="id106">identify_client()</a></li>
+<li><a class="reference" href="#client-fingerprint" id="id107" name="id107">client_fingerprint()</a></li>
+<li><a class="reference" href="#bdecode-bencode" id="id108" name="id108">bdecode() bencode()</a></li>
+<li><a class="reference" href="#supports-sparse-files" id="id109" name="id109">supports_sparse_files()</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#alerts" id="id108" name="id108">alerts</a><ul>
-<li><a class="reference" href="#listen-failed-alert" id="id109" name="id109">listen_failed_alert</a></li>
-<li><a class="reference" href="#portmap-error-alert" id="id110" name="id110">portmap_error_alert</a></li>
-<li><a class="reference" href="#portmap-alert" id="id111" name="id111">portmap_alert</a></li>
-<li><a class="reference" href="#file-error-alert" id="id112" name="id112">file_error_alert</a></li>
-<li><a class="reference" href="#tracker-announce-alert" id="id113" name="id113">tracker_announce_alert</a></li>
-<li><a class="reference" href="#tracker-alert" id="id114" name="id114">tracker_alert</a></li>
-<li><a class="reference" href="#tracker-reply-alert" id="id115" name="id115">tracker_reply_alert</a></li>
-<li><a class="reference" href="#tracker-warning-alert" id="id116" name="id116">tracker_warning_alert</a></li>
-<li><a class="reference" href="#url-seed-alert" id="id117" name="id117">url_seed_alert</a></li>
-<li><a class="reference" href="#hash-failed-alert" id="id118" name="id118">hash_failed_alert</a></li>
-<li><a class="reference" href="#peer-ban-alert" id="id119" name="id119">peer_ban_alert</a></li>
-<li><a class="reference" href="#peer-error-alert" id="id120" name="id120">peer_error_alert</a></li>
-<li><a class="reference" href="#invalid-request-alert" id="id121" name="id121">invalid_request_alert</a></li>
-<li><a class="reference" href="#torrent-finished-alert" id="id122" name="id122">torrent_finished_alert</a></li>
-<li><a class="reference" href="#metadata-failed-alert" id="id123" name="id123">metadata_failed_alert</a></li>
-<li><a class="reference" href="#metadata-received-alert" id="id124" name="id124">metadata_received_alert</a></li>
-<li><a class="reference" href="#fastresume-rejected-alert" id="id125" name="id125">fastresume_rejected_alert</a></li>
-<li><a class="reference" href="#peer-blocked-alert" id="id126" name="id126">peer_blocked_alert</a></li>
-<li><a class="reference" href="#storage-moved-alert" id="id127" name="id127">storage_moved_alert</a></li>
-<li><a class="reference" href="#torrent-paused-alert" id="id128" name="id128">torrent_paused_alert</a></li>
-<li><a class="reference" href="#dispatcher" id="id129" name="id129">dispatcher</a></li>
+<li><a class="reference" href="#alerts" id="id110" name="id110">alerts</a><ul>
+<li><a class="reference" href="#listen-failed-alert" id="id111" name="id111">listen_failed_alert</a></li>
+<li><a class="reference" href="#portmap-error-alert" id="id112" name="id112">portmap_error_alert</a></li>
+<li><a class="reference" href="#portmap-alert" id="id113" name="id113">portmap_alert</a></li>
+<li><a class="reference" href="#file-error-alert" id="id114" name="id114">file_error_alert</a></li>
+<li><a class="reference" href="#tracker-announce-alert" id="id115" name="id115">tracker_announce_alert</a></li>
+<li><a class="reference" href="#tracker-alert" id="id116" name="id116">tracker_alert</a></li>
+<li><a class="reference" href="#tracker-reply-alert" id="id117" name="id117">tracker_reply_alert</a></li>
+<li><a class="reference" href="#tracker-warning-alert" id="id118" name="id118">tracker_warning_alert</a></li>
+<li><a class="reference" href="#scrape-reply-alert" id="id119" name="id119">scrape_reply_alert</a></li>
+<li><a class="reference" href="#scrape-failed-alert" id="id120" name="id120">scrape_failed_alert</a></li>
+<li><a class="reference" href="#url-seed-alert" id="id121" name="id121">url_seed_alert</a></li>
+<li><a class="reference" href="#hash-failed-alert" id="id122" name="id122">hash_failed_alert</a></li>
+<li><a class="reference" href="#peer-ban-alert" id="id123" name="id123">peer_ban_alert</a></li>
+<li><a class="reference" href="#peer-error-alert" id="id124" name="id124">peer_error_alert</a></li>
+<li><a class="reference" href="#invalid-request-alert" id="id125" name="id125">invalid_request_alert</a></li>
+<li><a class="reference" href="#torrent-finished-alert" id="id126" name="id126">torrent_finished_alert</a></li>
+<li><a class="reference" href="#metadata-failed-alert" id="id127" name="id127">metadata_failed_alert</a></li>
+<li><a class="reference" href="#metadata-received-alert" id="id128" name="id128">metadata_received_alert</a></li>
+<li><a class="reference" href="#fastresume-rejected-alert" id="id129" name="id129">fastresume_rejected_alert</a></li>
+<li><a class="reference" href="#peer-blocked-alert" id="id130" name="id130">peer_blocked_alert</a></li>
+<li><a class="reference" href="#storage-moved-alert" id="id131" name="id131">storage_moved_alert</a></li>
+<li><a class="reference" href="#torrent-paused-alert" id="id132" name="id132">torrent_paused_alert</a></li>
+<li><a class="reference" href="#dispatcher" id="id133" name="id133">dispatcher</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#exceptions" id="id130" name="id130">exceptions</a><ul>
-<li><a class="reference" href="#invalid-handle" id="id131" name="id131">invalid_handle</a></li>
-<li><a class="reference" href="#duplicate-torrent" id="id132" name="id132">duplicate_torrent</a></li>
-<li><a class="reference" href="#invalid-encoding" id="id133" name="id133">invalid_encoding</a></li>
-<li><a class="reference" href="#type-error" id="id134" name="id134">type_error</a></li>
-<li><a class="reference" href="#invalid-torrent-file" id="id135" name="id135">invalid_torrent_file</a></li>
+<li><a class="reference" href="#exceptions" id="id134" name="id134">exceptions</a><ul>
+<li><a class="reference" href="#invalid-handle" id="id135" name="id135">invalid_handle</a></li>
+<li><a class="reference" href="#duplicate-torrent" id="id136" name="id136">duplicate_torrent</a></li>
+<li><a class="reference" href="#invalid-encoding" id="id137" name="id137">invalid_encoding</a></li>
+<li><a class="reference" href="#type-error" id="id138" name="id138">type_error</a></li>
+<li><a class="reference" href="#invalid-torrent-file" id="id139" name="id139">invalid_torrent_file</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#storage-interface" id="id136" name="id136">storage_interface</a><ul>
-<li><a class="reference" href="#initialize" id="id137" name="id137">initialize()</a></li>
-<li><a class="reference" href="#read" id="id138" name="id138">read()</a></li>
-<li><a class="reference" href="#write" id="id139" name="id139">write()</a></li>
-<li><a class="reference" href="#id11" id="id140" name="id140">move_storage()</a></li>
-<li><a class="reference" href="#verify-resume-data" id="id141" name="id141">verify_resume_data()</a></li>
-<li><a class="reference" href="#id12" id="id142" name="id142">write_resume_data()</a></li>
-<li><a class="reference" href="#move-slot" id="id143" name="id143">move_slot()</a></li>
-<li><a class="reference" href="#swap-slots" id="id144" name="id144">swap_slots()</a></li>
-<li><a class="reference" href="#swap-slots3" id="id145" name="id145">swap_slots3()</a></li>
-<li><a class="reference" href="#hash-for-slot" id="id146" name="id146">hash_for_slot()</a></li>
-<li><a class="reference" href="#release-files" id="id147" name="id147">release_files()</a></li>
-<li><a class="reference" href="#delete-files" id="id148" name="id148">delete_files()</a></li>
+<li><a class="reference" href="#storage-interface" id="id140" name="id140">storage_interface</a><ul>
+<li><a class="reference" href="#initialize" id="id141" name="id141">initialize()</a></li>
+<li><a class="reference" href="#read" id="id142" name="id142">read()</a></li>
+<li><a class="reference" href="#write" id="id143" name="id143">write()</a></li>
+<li><a class="reference" href="#id11" id="id144" name="id144">move_storage()</a></li>
+<li><a class="reference" href="#verify-resume-data" id="id145" name="id145">verify_resume_data()</a></li>
+<li><a class="reference" href="#id12" id="id146" name="id146">write_resume_data( )</a></li>
+<li><a class="reference" href="#move-slot" id="id147" name="id147">move_slot()</a></li>
+<li><a class="reference" href="#swap-slots" id="id148" name="id148">swap_slots()</a></li>
+<li><a class="reference" href="#swap-slots3" id="id149" name="id149">swap_slots3()</a></li>
+<li><a class="reference" href="#hash-for-slot" id="id150" name="id150">hash_for_slot()</a></li>
+<li><a class="reference" href="#release-files" id="id151" name="id151">release_files()</a></li>
+<li><a class="reference" href="#delete-files" id="id152" name="id152">delete_files()</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#fast-resume" id="id149" name="id149">fast resume</a><ul>
-<li><a class="reference" href="#file-format" id="id150" name="id150">file format</a></li>
+<li><a class="reference" href="#fast-resume" id="id153" name="id153">fast resume</a><ul>
+<li><a class="reference" href="#file-format" id="id154" name="id154">file format</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#threads" id="id151" name="id151">threads</a></li>
-<li><a class="reference" href="#storage-allocation" id="id152" name="id152">storage allocation</a><ul>
-<li><a class="reference" href="#sparse-allocation" id="id153" name="id153">sparse allocation</a></li>
-<li><a class="reference" href="#full-allocation" id="id154" name="id154">full allocation</a></li>
-<li><a class="reference" href="#compact-allocation" id="id155" name="id155">compact allocation</a></li>
+<li><a class="reference" href="#threads" id="id155" name="id155">threads</a></li>
+<li><a class="reference" href="#storage-allocation" id="id156" name="id156">storage allocation</a><ul>
+<li><a class="reference" href="#sparse-allocation" id="id157" name="id157">sparse allocation</a></li>
+<li><a class="reference" href="#full-allocation" id="id158" name="id158">full allocation</a></li>
+<li><a class="reference" href="#compact-allocation" id="id159" name="id159">compact allocation</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#extensions" id="id156" name="id156">extensions</a><ul>
-<li><a class="reference" href="#metadata-from-peers" id="id157" name="id157">metadata from peers</a></li>
-<li><a class="reference" href="#http-seeding" id="id158" name="id158">HTTP seeding</a></li>
+<li><a class="reference" href="#extensions" id="id160" name="id160">extensions</a><ul>
+<li><a class="reference" href="#metadata-from-peers" id="id161" name="id161">metadata from peers</a></li>
+<li><a class="reference" href="#http-seeding" id="id162" name="id162">HTTP seeding</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#filename-checks" id="id159" name="id159">filename checks</a></li>
-<li><a class="reference" href="#acknowledgments" id="id160" name="id160">acknowledgments</a></li>
+<li><a class="reference" href="#filename-checks" id="id163" name="id163">filename checks</a></li>
+<li><a class="reference" href="#acknowledgments" id="id164" name="id164">acknowledgments</a></li>
 </ul>
 </div>
 <div class="section">
@@ -201,7 +205,7 @@ the <tt class="docutils literal"><span class="pre">session</span></tt>, it conta
 <ul>
 <li><p class="first">construct a session</p>
 </li>
-<li><p class="first">parse .torrent-files and add them to the session (see <a class="reference" href="#bdecode-bencode">bdecode() bencode()</a>)</p>
+<li><p class="first">parse .torrent-files and add them to the session (see <a class="reference" href="#bdecode-bencode">bdecode() bencode()</a> and <a class="reference" href="#add-torrent">add_torrent()</a>)</p>
 </li>
 <li><p class="first">main loop (see <a class="reference" href="#session">session</a>)</p>
 <blockquote>
@@ -213,7 +217,7 @@ the <tt class="docutils literal"><span class="pre">session</span></tt>, it conta
 </blockquote>
 </li>
 <li><p class="first">save resume data for all torrent_handles (optional, see
-<a href="#id161" name="id162"><span class="problematic" id="id162">`write_resume_data()`_</span></a>)</p>
+<a class="reference" href="#write-resume-data">write_resume_data()</a>)</p>
 </li>
 <li><p class="first">destruct session object</p>
 </li>
@@ -221,7 +225,7 @@ the <tt class="docutils literal"><span class="pre">session</span></tt>, it conta
 <p>Each class and function is described in this manual.</p>
 </div>
 <div class="section">
-<h1><a id="primitive-network-types" name="primitive-network-types">primitive network types</a></h1>
+<h1><a id="network-primitives" name="network-primitives">network primitives</a></h1>
 <p>There are a few typedefs in the <tt class="docutils literal"><span class="pre">libtorrent</span></tt> namespace which pulls
 in network types from the <tt class="docutils literal"><span class="pre">asio</span></tt> namespace. These are:</p>
 <pre class="literal-block">
@@ -239,6 +243,7 @@ udp::endpoint
 </pre>
 <p>Which are the endpoint types used in libtorrent. An endpoint is an address
 with an associated port.</p>
+<p>For documentation on these types, please refer to the <a class="reference" href="http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html">asio documentation</a>.</p>
 </div>
 <div class="section">
 <h1><a id="session" name="session">session</a></h1>
@@ -274,7 +279,13 @@ class session: public boost::noncopyable
 
         session_proxy abort();
 
-        void remove_torrent(torrent_handle const&amp; h);
+        enum options_t
+        {
+                none = 0,
+                delete_files = 1
+        };
+
+        void remove_torrent(torrent_handle const&amp; h, int options = none);
         torrent_handle find_torrent(sha_hash const&amp; ih);
         std::vector&lt;torrent_handle&gt; get_torrents() const;
 
@@ -456,16 +467,27 @@ have metadata. See <tt class="docutils literal"><span class="pre">torrent_handle
 <tt class="docutils literal"><span class="pre">tracker_url</span></tt> can be 0.</p>
 </div>
 <div class="section">
-<h2><a id="remove-torrent-find-torrent-get-torrents" name="remove-torrent-find-torrent-get-torrents">remove_torrent() find_torrent() get_torrents()</a></h2>
+<h2><a id="remove-torrent" name="remove-torrent">remove_torrent()</a></h2>
+<blockquote>
+<pre class="literal-block">
+void remove_torrent(torrent_handle const&amp; h, int options = none);
+</pre>
+</blockquote>
+<p><tt class="docutils literal"><span class="pre">remove_torrent()</span></tt> will close all peer connections associated with the torrent and tell
+the tracker that we've stopped participating in the swarm. The optional second argument
+<tt class="docutils literal"><span class="pre">options</span></tt> can be used to delete all the files downloaded by this torrent. To do this, pass
+in the value <tt class="docutils literal"><span class="pre">session::delete_files</span></tt>. The removal of the torrent is asyncronous, there is
+no guarantee that adding the same torrent immediately after it was removed will not throw
+a <a class="reference" href="#duplicate-torrent">duplicate_torrent</a> exception.</p>
+</div>
+<div class="section">
+<h2><a id="find-torrent-get-torrents" name="find-torrent-get-torrents">find_torrent() get_torrents()</a></h2>
 <blockquote>
 <pre class="literal-block">
-void remove_torrent(torrent_handle const&amp; h);
 torrent_handle find_torrent(sha_hash const&amp; ih);
 std::vector&lt;torrent_handle&gt; get_torrents() const;
 </pre>
 </blockquote>
-<p><tt class="docutils literal"><span class="pre">remove_torrent()</span></tt> will close all peer connections associated with the torrent and tell
-the tracker that we've stopped participating in the swarm.</p>
 <p><tt class="docutils literal"><span class="pre">find_torrent()</span></tt> looks for a torrent with the given info-hash. In case there
 is such a torrent in the session, a torrent_handle to that torrent is returned.
 In case the torrent cannot be found, an invalid torrent_handle is returned.</p>
@@ -1401,6 +1423,8 @@ struct torrent_handle
 
         entry write_resume_data() const;
         void force_reannounce() const;
+        void force_reannounce(boost::posix_time::time_duration) const;
+        void scrape_tracker() const;
         void connect_peer(asio::ip::tcp::endpoint const&amp; adr, int source = 0) const;
 
         void set_tracker_login(std::string const&amp; username
@@ -1559,11 +1583,26 @@ thread, this operation is also asynchronous. Once the operation completes, the
 <blockquote>
 <pre class="literal-block">
 void force_reannounce() const;
+void force_reannounce(boost::posix_time::time_duration) const;
 </pre>
 </blockquote>
 <p><tt class="docutils literal"><span class="pre">force_reannounce()</span></tt> will force this torrent to do another tracker request, to receive new
-peers. If the torrent is invalid, queued or in checking mode, this functions will throw
-<a class="reference" href="#invalid-handle">invalid_handle</a>.</p>
+peers. The second overload of <tt class="docutils literal"><span class="pre">force_reannounce</span></tt> that takes a <tt class="docutils literal"><span class="pre">time_duration</span></tt> as
+argument will schedule a reannounce in that amount of time from now.</p>
+</div>
+<div class="section">
+<h2><a id="scrape-tracker" name="scrape-tracker">scrape_tracker()</a></h2>
+<blockquote>
+<pre class="literal-block">
+void scrape_tracker() const;
+</pre>
+</blockquote>
+<p><tt class="docutils literal"><span class="pre">scrape_tracker()</span></tt> will send a scrape request to the tracker. A scrape request queries the
+tracker for statistics such as total number of incomplete peers, complete peers, number of
+downloads etc.</p>
+<p>This request will specifically update the <tt class="docutils literal"><span class="pre">num_complete</span></tt> and <tt class="docutils literal"><span class="pre">num_incomplete</span></tt> fields in
+the <a class="reference" href="#torrent-status">torrent_status</a> struct once it completes. When it completes, it will generate a
+<a class="reference" href="#scrape-reply-alert">scrape_reply_alert</a>. If it fails, it will generate a <a class="reference" href="#scrape-failed-alert">scrape_failed_alert</a>.</p>
 </div>
 <div class="section">
 <h2><a id="connect-peer" name="connect-peer">connect_peer()</a></h2>
@@ -1936,6 +1975,7 @@ struct torrent_status
                 queued_for_checking,
                 checking_files,
                 connecting_to_tracker,
+                downloading_metadata,
                 downloading,
                 finished,
                 seeding,
@@ -2012,6 +2052,10 @@ currently checking existing files.</td>
 <td>The torrent has sent a request to the tracker and is
 currently waiting for a response</td>
 </tr>
+<tr><td><tt class="docutils literal"><span class="pre">downloading_metadata</span></tt></td>
+<td>The torrent is trying to download metadata from peers.
+This assumes the metadata_transfer extension is in use.</td>
+</tr>
 <tr><td><tt class="docutils literal"><span class="pre">downloading</span></tt></td>
 <td>The torrent is being downloaded. This is the state
 most torrents will be in most of the time. The progress
@@ -2362,6 +2406,7 @@ struct session_settings
         bool lazy_bitfields;
         int inactivity_timeout;
         bool use_dht_as_fallback;
+        bool free_torrent_hashes;
 };
 </pre>
 <p><tt class="docutils literal"><span class="pre">user_agent</span></tt> this is the client identification to the tracker.
@@ -2462,6 +2507,13 @@ Default is 10 minutes</p>
 (which it is by default), the DHT will only be used for torrents where
 all trackers in its tracker list has failed. Either by an explicit error
 message or a time out.</p>
+<p><tt class="docutils literal"><span class="pre">free_torrent_hashes</span></tt> determines whether or not the torrent's piece hashes
+are kept in memory after the torrent becomes a seed or not. If it is set to
+<tt class="docutils literal"><span class="pre">true</span></tt> the hashes are freed once the torrent is a seed (they're not
+needed anymore since the torrent won't download anything more). If it's set
+to false they are not freed. If they are freed, the <a class="reference" href="#torrent-info">torrent_info</a> returned
+by get_torrent_info() will return an object that may be incomplete, that
+cannot be passed back to <a class="reference" href="#add-torrent">add_torrent()</a> for instance.</p>
 </div>
 <div class="section">
 <h1><a id="pe-settings" name="pe-settings">pe_settings</a></h1>
@@ -3083,6 +3135,41 @@ struct tracker_warning_alert: torrent_alert
 </pre>
 </div>
 <div class="section">
+<h2><a id="scrape-reply-alert" name="scrape-reply-alert">scrape_reply_alert</a></h2>
+<pre class="literal-block">
+struct scrape_reply_alert: torrent_alert
+{
+        scrape_reply_alert(torrent_handle const&amp; h
+                , int incomplete_
+                , int complete_
+                , std::string const&amp; msg);
+
+        int incomplete;
+        int complete;
+
+        virtual std::auto_ptr&lt;alert&gt; clone() const;
+};
+</pre>
+<p>This alert is generated when a scrape request succeeds. <tt class="docutils literal"><span class="pre">incomplete</span></tt>
+and <tt class="docutils literal"><span class="pre">complete</span></tt> is the data returned in the scrape response. These numbers
+may be -1 if the reponse was malformed.</p>
+</div>
+<div class="section">
+<h2><a id="scrape-failed-alert" name="scrape-failed-alert">scrape_failed_alert</a></h2>
+<pre class="literal-block">
+struct scrape_failed_alert: torrent_alert
+{
+        scrape_failed_alert(torrent_handle const&amp; h
+                , std::string const&amp; msg);
+
+        virtual std::auto_ptr&lt;alert&gt; clone() const;
+};
+</pre>
+<p>If a scrape request fails, this alert is generated. This might be due
+to the tracker timing out, refusing connection or returning an http response
+code indicating an error.</p>
+</div>
+<div class="section">
 <h2><a id="url-seed-alert" name="url-seed-alert">url_seed_alert</a></h2>
 <p>This alert is generated when a HTTP seed name lookup fails. This alert is
 generated as severity level <tt class="docutils literal"><span class="pre">warning</span></tt>.</p>
@@ -3363,7 +3450,8 @@ struct invalid_handle: std::exception
 <div class="section">
 <h2><a id="duplicate-torrent" name="duplicate-torrent">duplicate_torrent</a></h2>
 <p>This is thrown by <a class="reference" href="#add-torrent">add_torrent()</a> if the torrent already has been added to
-the session.</p>
+the session. Since <a class="reference" href="#remove-torrent">remove_torrent()</a> is asynchronous, this exception may
+be thrown if the torrent is removed and then immediately added again.</p>
 <pre class="literal-block">
 struct duplicate_torrent: std::exception
 {
@@ -3484,7 +3572,7 @@ not, set <tt class="docutils literal"><span class="pre">error</span></tt> to a d
 <p>The default storage may compare file sizes and time stamps of the files.</p>
 </div>
 <div class="section">
-<h2><a id="id12" name="id12">write_resume_data()</a></h2>
+<h2><a id="id12" name="id12">write_resume_data( )</a></h2>
 <blockquote>
 <pre class="literal-block">
 void write_resume_data(entry&amp; rd) const = 0;
@@ -3986,12 +4074,6 @@ scripts.</p>
 <p>Project is hosted by sourceforge.</p>
 <p><a class="reference" href="http://sourceforge.net"><img alt="sf_logo" src="http://sourceforge.net/sflogo.php?group_id=7994" /></a></p>
 </div>
-<div class="system-messages section">
-<h1>Docutils System Messages</h1>
-<div class="system-message" id="id161">
-<p class="system-message-title">System Message: <a name="id161">ERROR/3</a> (<tt class="docutils">manual.rst</tt>, line 28); <em><a href="#id162">backlink</a></em></p>
-Duplicate target name, cannot be used as a unique reference: &quot;write_resume_data()&quot;.</div>
-</div>
 </div>
 </body>
 </html>
diff --git a/docs/manual.rst b/docs/manual.rst
index 6d4359b5d..32b0f98a6 100644
--- a/docs/manual.rst
+++ b/docs/manual.rst
@@ -18,7 +18,7 @@ the ``session``, it contains the main loop that serves all torrents.
 The basic usage is as follows:
 
 * construct a session
-* parse .torrent-files and add them to the session (see `bdecode() bencode()`_)
+* parse .torrent-files and add them to the session (see `bdecode() bencode()`_ and `add_torrent()`_)
 * main loop (see session_)
 
 	* query the torrent_handles for progress (see torrent_handle_)
@@ -31,8 +31,8 @@ The basic usage is as follows:
 
 Each class and function is described in this manual.
 
-primitive network types
-=======================
+network primitives
+==================
 
 There are a few typedefs in the ``libtorrent`` namespace which pulls
 in network types from the ``asio`` namespace. These are::
@@ -53,6 +53,11 @@ The ``using`` statements will give easy access to::
 Which are the endpoint types used in libtorrent. An endpoint is an address
 with an associated port.
 
+For documentation on these types, please refer to the `asio documentation`_.
+
+.. _`asio documentation`: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html
+
+
 session
 =======
 
@@ -290,21 +295,27 @@ If the torrent doesn't have a tracker, but relies on the DHT to find peers, the
 ``tracker_url`` can be 0.
 
 
-remove_torrent() find_torrent() get_torrents()
-----------------------------------------------
+remove_torrent()
+----------------
 
 	::
 
 		void remove_torrent(torrent_handle const& h, int options = none);
-		torrent_handle find_torrent(sha_hash const& ih);
-		std::vector<torrent_handle> get_torrents() const;
 
 ``remove_torrent()`` will close all peer connections associated with the torrent and tell
 the tracker that we've stopped participating in the swarm. The optional second argument
 ``options`` can be used to delete all the files downloaded by this torrent. To do this, pass
 in the value ``session::delete_files``. The removal of the torrent is asyncronous, there is
 no guarantee that adding the same torrent immediately after it was removed will not throw
-a ``duplicate_torrent`` exception.
+a duplicate_torrent_ exception.
+
+find_torrent() get_torrents()
+-----------------------------
+
+	::
+
+		torrent_handle find_torrent(sha_hash const& ih);
+		std::vector<torrent_handle> get_torrents() const;
 
 ``find_torrent()`` looks for a torrent with the given info-hash. In case there
 is such a torrent in the session, a torrent_handle to that torrent is returned.
@@ -3563,7 +3574,8 @@ duplicate_torrent
 -----------------
 
 This is thrown by `add_torrent()`_ if the torrent already has been added to
-the session.
+the session. Since `remove_torrent()`_ is asynchronous, this exception may
+be thrown if the torrent is removed and then immediately added again.
 
 ::