move some documentation over to headers and make all links in reference documentation work

docs/gen_reference_doc.py

@@ -26,6 +26,26 @@ overviews = {}
 # maps names -> URL
 symbols = {}
 
+# some pre-defined sections from the main manual
+
+symbols = \
+{
+	"queuing_": "manual.html#queuing",
+	"fast-resume_": "manual.html#fast-resume",
+	"storage-allocation_": "manual.html#storage-allocation",
+	"alerts_": "manual.html#alerts",
+	"upnp-and-nat-pmp_": "manual.html#upnp-and-nat-pmp",
+	"http-seeding_": "manual.html#http-seeding",
+	"metadata-from-peers_": "manual.html#metadata-from-peers",
+	"magnet-links_": "manual.html#magnet-links",
+}
+
+static_links = \
+{
+	".. _`BEP 17`: http://bittorrent.org/beps/bep_0017.html",
+	".. _`BEP 19`: http://bittorrent.org/beps/bep_0019.html"
+}
+
 anon_index = 0
 
 category_mapping = {
@@ -638,12 +658,19 @@ def linkify_symbols(string):
 			# preserve commas and dots at the end
 			w = words[i].strip()
 			trailing = ''
-			if len(w) > 0 and (w[-1] == '.' or w[-1] == ','):
+			if len(w) == 0: continue
+
+			if (w[-1] == '.' or w[-1] == ',' or (w[-1] == ')' and w[-2:-1] != '()')):
 				trailing = w[-1]
 				w = w[:-1]
-			
+
+			link_name = w;
+
+			if link_name[-1] == '_': link_name = link_name[:-1]
+
 			if w in symbols:
-				words[i] = (leading_tabs * '\t') + print_link(w, symbols[w]) + trailing
+				link_name = link_name.replace('-', ' ')
+				words[i] = (leading_tabs * '\t') + print_link(link_name, symbols[w]) + trailing
 		ret.append(' '.join(words))
 	return '\n'.join(ret)
 
@@ -847,5 +874,8 @@ for cat in categories:
 
 	print >>out, dump_link_targets()
 
+	for i in static_links:
+		print >>out, i
+
 	out.close()
 

docs/manual.rst

@@ -93,265 +93,6 @@ 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 customization
-=====================
-
-You have some control over session configuration through the ``session_settings`` object. You
-create it and fill it with your settings and then use ``session::set_settings()``
-to apply them.
-
-You have control over proxy and authorization settings and also the user-agent
-that will be sent to the tracker. The user-agent will also be used to identify the
-client with other peers.
-
-session_settings
-----------------
-
-::
-
-	struct session_settings
-	{
-		session_settings();
-		int version;
-		std::string user_agent;
-		int tracker_completion_timeout;
-		int tracker_receive_timeout;
-		int stop_tracker_timeout;
-		int tracker_maximum_response_length;
-
-		int piece_timeout;
-		float request_queue_time;
-		int max_allowed_in_request_queue;
-		int max_out_request_queue;
-		int whole_pieces_threshold;
-		int peer_timeout;
-		int urlseed_timeout;
-		int urlseed_pipeline_size;
-		int file_pool_size;
-		bool allow_multiple_connections_per_ip;
-		int max_failcount;
-		int min_reconnect_time;
-		int peer_connect_timeout;
-		bool ignore_limits_on_local_network;
-		int connection_speed;
-		bool send_redundant_have;
-		bool lazy_bitfields;
-		int inactivity_timeout;
-		int unchoke_interval;
-		int optimistic_unchoke_interval;
-		std::string announce_ip;
-		int num_want;
-		int initial_picker_threshold;
-		int allowed_fast_set_size;
-
-		enum { no_piece_suggestions = 0, suggest_read_cache = 1 };
-		int suggest_mode;
-		int max_queued_disk_bytes;
-		int handshake_timeout;
-		bool use_dht_as_fallback;
-		bool free_torrent_hashes;
-		bool upnp_ignore_nonrouters;
-		int send_buffer_watermark;
-		int send_buffer_watermark_factor;
-
-	#ifndef TORRENT_NO_DEPRECATE
-		bool auto_upload_slots;
-		bool auto_upload_slots_rate_based;
-	#endif
-
-		enum choking_algorithm_t
-		{
-			fixed_slots_choker,
-			auto_expand_choker,
-			rate_based_choker,
-			bittyrant_choker
-		};
-
-		int choking_algorithm;
-		
-		enum seed_choking_algorithm_t
-		{
-			round_robin,
-			fastest_upload,
-			anti_leech
-		};
-
-		int seed_choking_algorithm;
-
-		bool use_parole_mode;
-		int cache_size;
-		int cache_buffer_chunk_size;
-		int cache_expiry;
-		bool use_read_cache;
-		bool explicit_read_cache;
-		int explicit_cache_interval;
-
-		enum io_buffer_mode_t
-		{
-			enable_os_cache = 0,
-			disable_os_cache_for_aligned_files = 1,
-			disable_os_cache = 2
-		};
-		int disk_io_write_mode;
-		int disk_io_read_mode;
-
-		std::pair<int, int> outgoing_ports;
-		char peer_tos;
-
-		int active_downloads;
-		int active_seeds;
-		int active_dht_limit;
-		int active_tracker_limit;
-		int active_limit;
-		bool auto_manage_prefer_seeds;
-		bool dont_count_slow_torrents;
-		int auto_manage_interval;
-		float share_ratio_limit;
-		float seed_time_ratio_limit;
-		int seed_time_limit;
-		int peer_turnover_interval;
-		float peer_turnover;
-		float peer_turnover_cutoff;
-		bool close_redundant_connections;
-
-		int auto_scrape_interval;
-		int auto_scrape_min_interval;
-
-		int max_peerlist_size;
-
-		int min_announce_interval;
-
-		bool prioritize_partial_pieces;
-		int auto_manage_startup;
-
-		bool rate_limit_ip_overhead;
-
-		bool announce_to_all_trackers;
-		bool announce_to_all_tiers;
-
-		bool prefer_udp_trackers;
-		bool strict_super_seeding;
-
-		int seeding_piece_quota;
-
-		int max_sparse_regions;
-
-		bool lock_disk_cache;
-
-		int max_rejects;
-
-		int recv_socket_buffer_size;
-		int send_socket_buffer_size;
-
-		bool optimize_hashing_for_speed;
-
-		int file_checks_delay_per_block;
-
-		enum disk_cache_algo_t
-		{ lru, largest_contiguous, avoid_readback };
-
-		disk_cache_algo_t disk_cache_algorithm;
-
-		int read_cache_line_size;
-		int write_cache_line_size;
-
-		int optimistic_disk_retry;
-		bool disable_hash_checks;
-
-		int max_suggest_pieces;
-
-		bool drop_skipped_requests;
-
-		bool low_prio_disk;
-		int local_service_announce_interval;
-		int dht_announce_interval;
-
-		int udp_tracker_token_expiry;
-		bool volatile_read_cache;
-		bool guided_read_cache;
-		bool default_cache_min_age;
-
-		int num_optimistic_unchoke_slots;
-		bool no_atime_storage;
-		int default_est_reciprocation_rate;
-		int increase_est_reciprocation_rate;
-		int decrease_est_reciprocation_rate;
-		bool incoming_starts_queued_torrents;
-		bool report_true_downloaded;
-		bool strict_end_game_mode;
-
-		bool broadcast_lsd;
-
-		bool enable_outgoing_utp;
-		bool enable_incoming_utp;
-		bool enable_outgoing_tcp;
-		bool enable_incoming_tcp;
-		int max_pex_peers;
-		bool ignore_resume_timestamps;
-		bool no_recheck_incomplete_resume;
-		bool anonymous_mode;
-		bool force_proxy;
-		int tick_interval;
-		int share_mode_target;
-
-		int upload_rate_limit;
-		int download_rate_limit;
-		int local_upload_rate_limit;
-		int local_download_rate_limit;
-		int dht_upload_rate_limit;
-		int unchoke_slots_limit;
-		int half_open_limit;
-		int connections_limit;
-
-		int utp_target_delay;
-		int utp_gain_factor;
-		int utp_min_timeout;
-		int utp_syn_resends;
-		int utp_num_resends;
-		int utp_connect_timeout;
-		bool utp_dynamic_sock_buf;
-		int utp_loss_multiplier;
-
-		enum bandwidth_mixed_algo_t
-		{
-			prefer_tcp = 0,
-			peer_proportional = 1
-
-		};
-		int mixed_mode_algorithm;
-		bool rate_limit_utp;
-
-		int listen_queue_size;
-
-		bool announce_double_nat;
-
-		int torrent_connect_boost;
-		bool seeding_outgoing_connections;
-
-		bool no_connect_privileged_ports;
-		int alert_queue_size;
-		int max_metadata_size;
-		bool smooth_connects;
-		bool always_send_user_agent;
-		bool apply_ip_filter_to_trackers;
-		int read_job_every;
-		bool use_disk_read_ahead;
-		bool lock_files;
-
-		int ssl_listen;
-
-		int tracker_backoff;
-
-		bool ban_web_seeds;
-		int max_http_recv_buffer_size;
-
-		bool support_share_mode;
-		bool support_merkle_torrents;
-		bool report_redundant_bytes;
-		std::string handshake_client_version;
-		bool use_disk_cache_pool;
-	};
-
 exceptions
 ==========
 
@@ -362,65 +103,7 @@ error code on errors.
 There is one exception class that is used for errors in libtorrent, it is based
 on boost.system's ``error_code`` class to carry the error code.
 
-libtorrent_exception
+For more information, see libtorrent_exception and error_code_enum.
---------------------
-
-::
-
-	struct libtorrent_exception: std::exception
-	{
-		libtorrent_exception(error_code const& s);
-		virtual const char* what() const throw();
-		virtual ~libtorrent_exception() throw() {}
-		boost::system::error_code error() const;
-	};
-
-
-error_code
-==========
-
-The names of these error codes are declared in then ``libtorrent::errors`` namespace.
-
-HTTP errors are reported in the ``libtorrent::http_category``, with error code enums in
-the ``libtorrent::errors`` namespace.
-
-====== =========================================
-code   symbol                                   
-====== =========================================
-100    cont                                     
------- -----------------------------------------
-200    ok                                       
------- -----------------------------------------
-201    created                                  
------- -----------------------------------------
-202    accepted                                 
------- -----------------------------------------
-204    no_content                               
------- -----------------------------------------
-300    multiple_choices                         
------- -----------------------------------------
-301    moved_permanently                        
------- -----------------------------------------
-302    moved_temporarily                        
------- -----------------------------------------
-304    not_modified                             
------- -----------------------------------------
-400    bad_request                              
------- -----------------------------------------
-401    unauthorized                             
------- -----------------------------------------
-403    forbidden                                
------- -----------------------------------------
-404    not_found                                
------- -----------------------------------------
-500    internal_server_error                    
------- -----------------------------------------
-501    not_implemented                          
------- -----------------------------------------
-502    bad_gateway                              
------- -----------------------------------------
-503    service_unavailable                      
-====== =========================================
 
 translating error codes
 -----------------------
@@ -474,64 +157,6 @@ Here's a simple example of how to translate error codes::
 storage_interface
 =================
 
-The storage interface is a pure virtual class that can be implemented to
-customize how and where data for a torrent is stored. The default storage
-implementation uses regular files in the filesystem, mapping the files in the
-torrent in the way one would assume a torrent is saved to disk. Implementing
-your own storage interface makes it possible to store all data in RAM, or in
-some optimized order on disk (the order the pieces are received for instance),
-or saving multifile torrents in a single file in order to be able to take
-advantage of optimized disk-I/O.
-
-It is also possible to write a thin class that uses the default storage but
-modifies some particular behavior, for instance encrypting the data before
-it's written to disk, and decrypting it when it's read again.
-
-The storage interface is based on slots, each slot is 'piece_size' number
-of bytes. All access is done by writing and reading whole or partial
-slots. One slot is one piece in the torrent, but the data in the slot
-does not necessarily correspond to the piece with the same index (in
-compact allocation mode it won't).
-
-libtorrent comes with two built-in storage implementations; ``default_storage``
-and ``disabled_storage``. Their constructor functions are called ``default_storage_constructor``
-and ``disabled_storage_constructor`` respectively. The disabled storage does
-just what it sounds like. It throws away data that's written, and it
-reads garbage. It's useful mostly for benchmarking and profiling purpose.
-
-
-The interface looks like this::
-
-	struct storage_interface
-	{
-		virtual bool initialize(bool allocate_files) = 0;
-		virtual bool has_any_file() = 0;
-		virtual void hint_read(int slot, int offset, int len);
-		virtual int readv(file::iovec_t const* bufs, int slot, int offset, int num_bufs) = 0;
-		virtual int writev(file::iovec_t const* bufs, int slot, int offset, int num_bufs) = 0;
-		virtual int sparse_end(int start) const;
-		virtual bool move_storage(fs::path save_path) = 0;
-		virtual bool verify_resume_data(lazy_entry const& rd, error_code& error) = 0;
-		virtual bool write_resume_data(entry& rd) const = 0;
-		virtual bool move_slot(int src_slot, int dst_slot) = 0;
-		virtual bool swap_slots(int slot1, int slot2) = 0;
-		virtual bool swap_slots3(int slot1, int slot2, int slot3) = 0;
-		virtual bool rename_file(int file, std::string const& new_name) = 0;
-		virtual bool release_files() = 0;
-		virtual bool delete_files() = 0;
-		virtual void finalize_file(int index) {}
-		virtual ~storage_interface() {}
-
-		// non virtual functions
-
-		disk_buffer_pool* disk_pool();
-		void set_error(std::string const& file, error_code const& ec) const;
-		error_code const& error() const;
-		std::string const& error_file() const;
-		void clear_error();
-	};
-
-
 initialize()
 ------------
 

include/libtorrent/add_torrent_params.hpp

@@ -248,11 +248,11 @@ namespace libtorrent
 
 		// The optional parameter, ``resume_data`` can be given if up to date fast-resume data
 		// is available. The fast-resume data can be acquired from a running torrent by calling
-		// save_resume_data() on `torrent_handle`_. See `fast resume`_. The ``vector`` that is
+		// save_resume_data() on `torrent_handle`_. See fast-resume_. The ``vector`` that is
 		// passed in will be swapped into the running torrent instance with ``std::vector::swap()``.
 		std::vector<char> resume_data;
 
-		// One of the values from storage_mode_t. For more information, see `storage allocation`_.
+		// One of the values from storage_mode_t. For more information, see storage-allocation_.
 		storage_mode_t storage_mode;
 
 		// can be used to customize how the data is stored. The default

include/libtorrent/error_code.hpp

@@ -430,6 +430,8 @@ namespace libtorrent
 			error_code_max
 		};
 
+		// HTTP errors are reported in the libtorrent::http_category, with error code enums in
+		// the ``libtorrent::errors`` namespace.
 		enum http_errors
 		{
 			cont = 100,

include/libtorrent/magnet_uri.hpp

@@ -46,7 +46,7 @@ namespace libtorrent
 	// Generates a magnet URI from the specified torrent. If the torrent
 	// handle is invalid, an empty string is returned.
 	// 
-	// For more information about magnet links, see `magnet links`_.
+	// For more information about magnet links, see magnet-links_.
 	// 
 	std::string TORRENT_EXPORT make_magnet_uri(torrent_handle const& handle);
 	std::string TORRENT_EXPORT make_magnet_uri(torrent_info const& info);

include/libtorrent/peer_info.hpp

@@ -192,6 +192,8 @@ namespace libtorrent
 		
 		// the IP-address to this peer. The type is an asio endpoint. For
 		// more info, see the asio_ documentation.
+		//
+		// .. _asio: http://asio.sourceforge.net/asio-0.3.8/doc/asio/reference.html
 		tcp::endpoint ip;
 
 		// the current upload and download speed

include/libtorrent/session.hpp

@@ -689,7 +689,7 @@ namespace libtorrent
 		// These functions sets and queries the proxy settings to be used for the session.
 		//
 		// For more information on what settings are available for proxies, see
-		// `proxy_settings`_.
+		// proxy_settings.
 		void set_proxy(proxy_settings const& s);
 		proxy_settings proxy() const;
 
@@ -854,7 +854,7 @@ namespace libtorrent
 		// The upnp object returned by ``start_upnp()`` can be used to add and remove
 		// arbitrary port mappings. Mapping status is returned through the
 		// portmap_alert and the portmap_error_alert. The object will be valid until
-		// ``stop_upnp()`` is called. See `UPnP and NAT-PMP`_.
+		// ``stop_upnp()`` is called. See upnp-and-nat-pmp_.
 		// 
 		// It is off by default.
  		void start_upnp();
@@ -866,7 +866,7 @@ namespace libtorrent
 		// The natpmp object returned by ``start_natpmp()`` can be used to add and remove
 		// arbitrary port mappings. Mapping status is returned through the
 		// portmap_alert and the portmap_error_alert. The object will be valid until
-		// ``stop_natpmp()`` is called. See `UPnP and NAT-PMP`_.
+		// ``stop_natpmp()`` is called. See upnp-and-nat-pmp_.
 		// 
 		// It is off by default.
 		void start_natpmp();

include/libtorrent/session_settings.hpp

@@ -378,9 +378,9 @@ namespace libtorrent
 		// are kept in memory after the torrent becomes a seed or not. If it is set to
 		// ``true`` 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 torrent_info_ returned
+		// to false they are not freed. If they are freed, the torrent_info returned
 		// by get_torrent_info() will return an object that may be incomplete, that
-		// cannot be passed back to `async_add_torrent() add_torrent()`_ for instance.
+		// cannot be passed back to async_add_torrent() and add_torrent() for instance.
 		bool free_torrent_hashes;
 
 		// indicates whether or not the UPnP implementation
@@ -798,7 +798,7 @@ namespace libtorrent
 		int max_sparse_regions;
 
 #ifndef TORRENT_DISABLE_MLOCK
-		//  if lock disk cache is set to true the disk cache
+		// if lock disk cache is set to true the disk cache
 		// that's in use, will be locked in physical memory, preventing it from
 		// being swapped out.
 		bool lock_disk_cache;

include/libtorrent/storage.hpp

@@ -99,6 +99,30 @@ namespace libtorrent
 		hasher h;
 	};
 
+	// The storage interface is a pure virtual class that can be implemented to
+	// customize how and where data for a torrent is stored. The default storage
+	// implementation uses regular files in the filesystem, mapping the files in the
+	// torrent in the way one would assume a torrent is saved to disk. Implementing
+	// your own storage interface makes it possible to store all data in RAM, or in
+	// some optimized order on disk (the order the pieces are received for instance),
+	// or saving multifile torrents in a single file in order to be able to take
+	// advantage of optimized disk-I/O.
+	// 
+	// It is also possible to write a thin class that uses the default storage but
+	// modifies some particular behavior, for instance encrypting the data before
+	// it's written to disk, and decrypting it when it's read again.
+	// 
+	// The storage interface is based on slots, each slot is 'piece_size' number
+	// of bytes. All access is done by writing and reading whole or partial
+	// slots. One slot is one piece in the torrent, but the data in the slot
+	// does not necessarily correspond to the piece with the same index (in
+	// compact allocation mode it won't).
+	// 
+	// libtorrent comes with two built-in storage implementations; ``default_storage``
+	// and ``disabled_storage``. Their constructor functions are called ``default_storage_constructor``
+	// and ``disabled_storage_constructor`` respectively. The disabled storage does
+	// just what it sounds like. It throws away data that's written, and it
+	// reads garbage. It's useful mostly for benchmarking and profiling purpose.
 	struct TORRENT_EXPORT storage_interface
 	{
 		storage_interface(): m_disk_pool(0), m_settings(0) {}

include/libtorrent/torrent_handle.hpp

@@ -404,15 +404,15 @@ namespace libtorrent
 		// currently in this torrent. Note that urls that fails may be removed
 		// automatically from the list.
 		// 
-		// See `HTTP seeding`_ for more information.
+		// See http-seeding_ for more information.
 		void add_url_seed(std::string const& url) const;
 		void remove_url_seed(std::string const& url) const;
 		std::set<std::string> url_seeds() const;
 
 		// These functions are identical as the ``*_url_seed()`` variants, but they
-		// operate on BEP 17 web seeds instead of BEP 19.
+		// operate on `BEP 17`_ web seeds instead of `BEP 19`_.
 		// 
-		// See `HTTP seeding`_ for more information.
+		// See http-seeding_ for more information.
 		void add_http_seed(std::string const& url) const;
 		void remove_http_seed(std::string const& url) const;
 		std::set<std::string> http_seeds() const;
@@ -498,7 +498,7 @@ namespace libtorrent
 		enum save_resume_flags_t { flush_disk_cache = 1, save_info_dict = 2 };
 
 		// ``save_resume_data()`` generates fast-resume data and returns it as an entry. This entry
-		// is suitable for being bencoded. For more information about how fast-resume works, see `fast resume`_.
+		// is suitable for being bencoded. For more information about how fast-resume works, see fast-resume_.
 		// 
 		// The ``flags`` argument is a bitmask of flags ORed together. If the flag ``torrent_handle::flush_cache``
 		// is set, the disk cache will be flushed before creating the resume data. This avoids a problem with
@@ -517,7 +517,7 @@ namespace libtorrent
 		//	2. The torrent is checking (or is queued for checking) its storage, it will obviously
 		//	   not be ready to write resume data.
 		//	3. The torrent hasn't received valid metadata and was started without metadata
-		//	   (see libtorrent's `metadata from peers`_ extension)
+		//	   (see libtorrent's metadata-from-peers_ extension)
 		// 
 		// Note that by the time you receive the fast resume data, it may already be invalid if the torrent
 		// is still downloading! The recommended practice is to first pause the session, then generate the
@@ -1312,7 +1312,7 @@ namespace libtorrent
 		int connections_limit;
 
 		// The allocation mode for the torrent. See storage_mode_t for the options.
-		// For more information, see `Storage allocation`_.
+		// For more information, see storage-allocation_.
 		storage_mode_t storage_mode;
 
 		// the number of peers in this

include/libtorrent/torrent_info.hpp

@@ -414,7 +414,7 @@ namespace libtorrent
 		// The ``extra_headers`` argument defaults to an empty list, but can be used to
 		// insert custom HTTP headers in the requests to a specific web seed.
 		// 
-		// See `HTTP seeding`_ for more information.
+		// See http-seeding_ for more information.
  		void add_url_seed(std::string const& url
 			, std::string const& extern_auth = std::string()
 			, web_seed_entry::headers_t const& extra_headers = web_seed_entry::headers_t());