more documentation polishing. the manual.rst is now also linked to the reference documentation
This commit is contained in:
Arvid Norberg
parent
6036cdcf6b
commit
000addec8a
|
|
@ -26,8 +26,14 @@ overviews = {}
|
|||
# maps names -> URL
|
||||
symbols = {}
|
||||
|
||||
# some pre-defined sections from the main manual
|
||||
# some files that need pre-processing to turn symbols into
|
||||
# links into the reference documentation
|
||||
preprocess_rst = \
|
||||
{
|
||||
'manual.rst':'manual-ref.rst',
|
||||
}
|
||||
|
||||
# some pre-defined sections from the main manual
|
||||
symbols = \
|
||||
{
|
||||
"queuing_": "manual.html#queuing",
|
||||
|
|
@ -120,6 +126,7 @@ def is_visible(desc):
|
|||
def highlight_signature(s):
|
||||
name = s.split('(')
|
||||
name2 = name[0].split(' ')
|
||||
if len(name2[-1]) == 0: return s
|
||||
name2[-1] = '**' + name2[-1] + '** '
|
||||
name[0] = ' '.join(name2)
|
||||
return '('.join(name)
|
||||
|
|
@ -495,7 +502,7 @@ for filename in files:
|
|||
continue
|
||||
|
||||
if 'TORRENT_EXPORT ' in l or l.startswith('inline ') or internal:
|
||||
if 'class ' in l or 'struct ' in l:
|
||||
if l.startswith('class ') or l.startswith('struct '):
|
||||
if not l.endswith(';'):
|
||||
current_class, lno = parse_class(lno -1, lines, filename)
|
||||
if current_class != None and is_visible(context):
|
||||
|
|
@ -638,15 +645,28 @@ def print_declared_in(out, o):
|
|||
# returns RST marked up string
|
||||
def linkify_symbols(string):
|
||||
lines = string.split('\n')
|
||||
abort = False
|
||||
ret = []
|
||||
in_literal = False
|
||||
for l in lines:
|
||||
if l.endswith('::'):
|
||||
abort = True
|
||||
if abort:
|
||||
if l.startswith('|'):
|
||||
ret.append(l)
|
||||
continue
|
||||
if in_literal and not l.startswith('\t') and not l == '':
|
||||
# print ' end literal: "%s"' % l
|
||||
in_literal = False
|
||||
if in_literal:
|
||||
# print ' literal: "%s"' % l
|
||||
ret.append(l)
|
||||
continue
|
||||
if l.endswith('::'):
|
||||
# print ' start literal: "%s"' % l
|
||||
in_literal = True
|
||||
words = l.split(' ')
|
||||
|
||||
if len(words) == 1:
|
||||
ret.append(l)
|
||||
continue
|
||||
|
||||
for i in range(len(words)):
|
||||
# it's important to preserve leading
|
||||
# tabs, since that's relevant for
|
||||
|
|
@ -658,18 +678,24 @@ def linkify_symbols(string):
|
|||
# preserve commas and dots at the end
|
||||
w = words[i].strip()
|
||||
trailing = ''
|
||||
|
||||
if len(w) == 0: continue
|
||||
|
||||
if (w[-1] == '.' or w[-1] == ',' or (w[-1] == ')' and w[-2:-1] != '()')):
|
||||
trailing = w[-1]
|
||||
while len(w) > 1 and (w[-1] == '.' or w[-1] == ',' or (w[-1] == ')' and w[-2:] != '()')):
|
||||
trailing = w[-1] + trailing
|
||||
w = w[:-1]
|
||||
|
||||
link_name = w;
|
||||
|
||||
# print w
|
||||
|
||||
if len(w) == 0: continue
|
||||
|
||||
if link_name[-1] == '_': link_name = link_name[:-1]
|
||||
|
||||
if w in symbols:
|
||||
link_name = link_name.replace('-', ' ')
|
||||
# print ' found %s -> %s' % (w, link_name)
|
||||
words[i] = (leading_tabs * '\t') + print_link(link_name, symbols[w]) + trailing
|
||||
ret.append(' '.join(words))
|
||||
return '\n'.join(ret)
|
||||
|
|
@ -879,3 +905,19 @@ for cat in categories:
|
|||
|
||||
out.close()
|
||||
|
||||
#for s in symbols:
|
||||
# print s
|
||||
|
||||
for i,o in preprocess_rst.items():
|
||||
f = open(i, 'r')
|
||||
out = open(o, 'w+')
|
||||
print 'processing %s -> %s' % (i, o)
|
||||
l = linkify_symbols(f.read())
|
||||
print >>out, l,
|
||||
|
||||
print >>out, dump_link_targets()
|
||||
|
||||
out.close()
|
||||
f.close()
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,8 @@
|
|||
* contributing_
|
||||
* `building libtorrent`_
|
||||
* examples_
|
||||
* `api documentation`_
|
||||
* `library overview`_
|
||||
* `reference documentation`_
|
||||
* `create torrents`_
|
||||
* `running tests`_
|
||||
* `tuning`_
|
||||
|
|
@ -58,7 +59,8 @@ libtorrent
|
|||
.. _contributing: contributing.html
|
||||
.. _`building libtorrent`: building.html
|
||||
.. _examples: examples.html
|
||||
.. _`api documentation`: manual.html
|
||||
.. _`library overview`: manual-ref.html
|
||||
.. _`reference documentation`: reference.html
|
||||
.. _`create torrents`: make_torrent.html
|
||||
.. _`running tests`: running_tests.html
|
||||
.. _`tuning`: tuning.html
|
||||
|
|
|
|||
|
|
@ -17,14 +17,14 @@ REFERENCE_TARGETS = \
|
|||
reference-Alerts \
|
||||
reference-RSS \
|
||||
reference-Filter \
|
||||
reference-Settings
|
||||
reference-Settings \
|
||||
manual-ref
|
||||
|
||||
TARGETS = index \
|
||||
udp_tracker_protocol \
|
||||
dht_rss \
|
||||
dht_store \
|
||||
client_test \
|
||||
manual \
|
||||
building \
|
||||
features \
|
||||
contributing\
|
||||
|
|
@ -55,7 +55,7 @@ all: html
|
|||
todo.html:gen_todo.py ../src/*.cpp ../include/libtorrent/*.hpp
|
||||
python gen_todo.py
|
||||
|
||||
$(REFERENCE_TARGETS:=.rst):gen_reference_doc.py ../include/libtorrent/*.hpp ../include/libtorrent/kademlia/*.hpp
|
||||
$(REFERENCE_TARGETS:=.rst):gen_reference_doc.py ../include/libtorrent/*.hpp ../include/libtorrent/kademlia/*.hpp manual.rst
|
||||
python gen_reference_doc.py
|
||||
|
||||
%.epub:%.rst
|
||||
|
|
|
|||
|
|
@ -18,25 +18,26 @@ the ``session``, it contains the main loop that serves all torrents.
|
|||
The basic usage is as follows:
|
||||
|
||||
* construct a session
|
||||
* load session state from settings file (see `load_state() save_state()`_)
|
||||
* start extensions (see `add_extension()`_).
|
||||
* start DHT, LSD, UPnP, NAT-PMP etc (see `start_dht() stop_dht() set_dht_settings() dht_state() is_dht_running()`_
|
||||
`start_lsd() stop_lsd()`_, `start_upnp() stop_upnp()`_ and `start_natpmp() stop_natpmp()`_)
|
||||
* parse .torrent-files and add them to the session (see `bdecode() bencode()`_ and `async_add_torrent() add_torrent()`_)
|
||||
* main loop (see session_)
|
||||
* load session state from settings file (see load_state())
|
||||
* start extensions (see add_extension()).
|
||||
* start DHT, LSD, UPnP, NAT-PMP etc (see start_dht(), start_lsd(), start_upnp() and start_natpmp()).
|
||||
* parse .torrent-files and add them to the session (see torrent_info, async_add_torrent() and add_torrent())
|
||||
* main loop (see session)
|
||||
|
||||
* query the torrent_handles for progress (see torrent_handle_)
|
||||
* query the session for information
|
||||
* add and remove torrents from the session at run-time
|
||||
* poll for alerts (see wait_for_alert(), pop_alerts())
|
||||
* handle updates to torrents, (see state_update_alert).
|
||||
* handle other alerts, (see alert).
|
||||
* query the session for information (see session::status()).
|
||||
* add and remove torrents from the session (remove_torrent())
|
||||
|
||||
* save resume data for all torrent_handles (optional, see
|
||||
`save_resume_data()`_)
|
||||
* save session state (see `load_state() save_state()`_)
|
||||
save_resume_data())
|
||||
* save session state (see save_state())
|
||||
* destruct session object
|
||||
|
||||
Each class and function is described in this manual.
|
||||
|
||||
For a description on how to create torrent files, see make_torrent_.
|
||||
For a description on how to create torrent files, see make_torrent.
|
||||
|
||||
.. _make_torrent: make_torrent.html
|
||||
|
||||
|
|
@ -64,7 +65,7 @@ the write error is caused by a full disk or write permission errors. If the
|
|||
torrent is auto-managed, it will periodically be taken out of the upload
|
||||
mode, trying to write things to the disk again. This means torrent will recover
|
||||
from certain disk errors if the problem is resolved. If the torrent is not
|
||||
auto managed, you have to call `set_upload_mode()`_ to turn
|
||||
auto managed, you have to call set_upload_mode() to turn
|
||||
downloading back on again.
|
||||
|
||||
network primitives
|
||||
|
|
@ -193,7 +194,6 @@ opportunity to hint the operating system about this coming read. For instance, t
|
|||
storage may call ``posix_fadvise(POSIX_FADV_WILLNEED)`` or ``fcntl(F_RDADVISE)``.
|
||||
|
||||
readv() writev()
|
||||
----------------
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -479,7 +479,7 @@ download, without any .torrent file.
|
|||
|
||||
The format of the magnet URI is:
|
||||
|
||||
**magnet:?xt=urn:btih:** *Base32 encoded info-hash* [ **&dn=** *name of download* ] [ **&tr=** *tracker URL* ]*
|
||||
**magnet:?xt=urn:btih:** *Base16 encoded info-hash* [ **&dn=** *name of download* ] [ **&tr=** *tracker URL* ]*
|
||||
|
||||
queuing
|
||||
=======
|
||||
|
|
@ -490,10 +490,10 @@ downloaded, the next in line is started.
|
|||
|
||||
Torrents that are *auto managed* are subject to the queuing and the active torrents
|
||||
limits. To make a torrent auto managed, set ``auto_managed`` to true when adding the
|
||||
torrent (see `async_add_torrent() add_torrent()`_).
|
||||
torrent (see async_add_torrent() and add_torrent()).
|
||||
|
||||
The limits of the number of downloading and seeding torrents are controlled via
|
||||
``active_downloads``, ``active_seeds`` and ``active_limit`` in session_settings_.
|
||||
``active_downloads``, ``active_seeds`` and ``active_limit`` in session_settings.
|
||||
These limits takes non auto managed torrents into account as well. If there are
|
||||
more non-auto managed torrents being downloaded than the ``active_downloads``
|
||||
setting, any auto managed torrents will be queued until torrents are removed so
|
||||
|
|
@ -503,10 +503,10 @@ The default values are 8 active downloads and 5 active seeds.
|
|||
|
||||
At a regular interval, torrents are checked if there needs to be any re-ordering of
|
||||
which torrents are active and which are queued. This interval can be controlled via
|
||||
``auto_manage_interval`` in session_settings_. It defaults to every 30 seconds.
|
||||
``auto_manage_interval`` in session_settings. It defaults to every 30 seconds.
|
||||
|
||||
For queuing to work, resume data needs to be saved and restored for all torrents.
|
||||
See `save_resume_data()`_.
|
||||
See save_resume_data().
|
||||
|
||||
downloading
|
||||
-----------
|
||||
|
|
@ -524,7 +524,7 @@ Lower queue position means closer to the front of the queue, and will be started
|
|||
torrents with higher queue positions.
|
||||
|
||||
To query a torrent for its position in the queue, or change its position, see:
|
||||
`queue_position() queue_position_up() queue_position_down() queue_position_top() queue_position_bottom()`_.
|
||||
queue_position(), queue_position_up(), queue_position_down(), queue_position_top() and queue_position_bottom().
|
||||
|
||||
seeding
|
||||
-------
|
||||
|
|
@ -536,7 +536,7 @@ seeding. A seed cycle is completed when a torrent meets either the share ratio l
|
|||
downloaing) or seed time limit (time seeded).
|
||||
|
||||
The relevant settings to control these limits are ``share_ratio_limit``,
|
||||
``seed_time_ratio_limit`` and ``seed_time_limit`` in session_settings_.
|
||||
``seed_time_ratio_limit`` and ``seed_time_limit`` in session_settings.
|
||||
|
||||
|
||||
fast resume
|
||||
|
|
@ -544,14 +544,14 @@ fast resume
|
|||
|
||||
The fast resume mechanism is a way to remember which pieces are downloaded
|
||||
and where they are put between sessions. You can generate fast resume data by
|
||||
calling `save_resume_data()`_ on torrent_handle_. You can
|
||||
calling save_resume_data() on torrent_handle. You can
|
||||
then save this data to disk and use it when resuming the torrent. libtorrent
|
||||
will not check the piece hashes then, and rely on the information given in the
|
||||
fast-resume data. The fast-resume data also contains information about which
|
||||
blocks, in the unfinished pieces, were downloaded, so it will not have to
|
||||
start from scratch on the partially downloaded pieces.
|
||||
|
||||
To use the fast-resume data you simply give it to `async_add_torrent() add_torrent()`_, and it
|
||||
To use the fast-resume data you simply give it to async_add_torrent() and add_torrent(), and it
|
||||
will skip the time consuming checks. It may have to do the checking anyway, if
|
||||
the fast-resume data is corrupt or doesn't fit the storage for that torrent,
|
||||
then it will not trust the fast-resume data and just do the checking.
|
||||
|
|
@ -730,7 +730,7 @@ Support for this is deprecated and will be removed in future versions of libtorr
|
|||
It's still described in here for completeness.
|
||||
|
||||
The allocation mode is selected when a torrent is started. It is passed as an
|
||||
argument to ``session::add_torrent()`` (see `async_add_torrent() add_torrent()`_).
|
||||
argument to session::add_torrent() or session::async_add_torrent().
|
||||
|
||||
The decision to use full allocation or compact allocation typically depends on whether
|
||||
any files have priority 0 and if the filesystem supports sparse files.
|
||||
|
|
@ -839,12 +839,12 @@ allocating a new slot:
|
|||
extensions
|
||||
==========
|
||||
|
||||
These extensions all operates within the `extension protocol`__. The
|
||||
These extensions all operates within the `extension protocol`_. The
|
||||
name of the extension is the name used in the extension-list packets,
|
||||
and the payload is the data in the extended message (not counting the
|
||||
length-prefix, message-id nor extension-id).
|
||||
|
||||
__ extension_protocol.html
|
||||
.. _`extension protocol`: extension_protocol.html
|
||||
|
||||
Note that since this protocol relies on one of the reserved bits in the
|
||||
handshake, it may be incompatible with future versions of the mainline
|
||||
|
|
@ -1024,7 +1024,7 @@ the client from getting started into the normal tit-for-tat mode of
|
|||
bittorrent, and will result in a long ramp-up time. The heuristic to
|
||||
mitigate this problem is to, for the first few pieces, pick random pieces
|
||||
rather than rare pieces. The threshold for when to leave this initial
|
||||
picker mode is determined by ``session_settings::initial_picker_threshold``.
|
||||
picker mode is determined by session_settings::initial_picker_threshold.
|
||||
|
||||
reverse order
|
||||
-------------
|
||||
|
|
@ -1043,7 +1043,7 @@ parole mode
|
|||
Peers that have participated in a piece that failed the hash check, may be
|
||||
put in *parole mode*. This means we prefer downloading a full piece from this
|
||||
peer, in order to distinguish which peer is sending corrupt data. Whether to
|
||||
do this is or not is controlled by ``session_settings::use_parole_mode``.
|
||||
do this is or not is controlled by session_settings::use_parole_mode.
|
||||
|
||||
In parole mode, the piece picker prefers picking one whole piece at a time for
|
||||
a given peer, avoiding picking any blocks from a piece any other peer has
|
||||
|
|
@ -1057,7 +1057,7 @@ be preferred over other pieces. The benefit of doing this is that the number of
|
|||
partial pieces is minimized (and hence the turn-around time for downloading a block
|
||||
until it can be uploaded to others is minimized). It also puts less stress on the
|
||||
disk cache, since fewer partial pieces need to be kept in the cache. Whether or
|
||||
not to enable this is controlled by ``session_settings::prioritize_partial_pieces``.
|
||||
not to enable this is controlled by session_settings::prioritize_partial_pieces.
|
||||
|
||||
The main benefit of not prioritizing partial pieces is that the rarest first
|
||||
algorithm gets to have more influence on which pieces are picked. The picker is
|
||||
|
|
@ -1083,7 +1083,7 @@ threshold. The main advantage is that these peers will better utilize the
|
|||
other peer's disk cache, by requesting all blocks in a single piece, from
|
||||
the same peer.
|
||||
|
||||
This threshold is controlled by ``session_settings::whole_pieces_threshold``.
|
||||
This threshold is controlled by session_settings::whole_pieces_threshold.
|
||||
|
||||
*TODO: piece affinity by speed category*
|
||||
*TODO: piece priorities*
|
||||
|
|
@ -1111,9 +1111,9 @@ certificates are expected to be privided to peers through some other means than
|
|||
bittorrent. Typically by a peer generating a certificate request which is sent to
|
||||
the publisher of the torrent, and the publisher returning a signed certificate.
|
||||
|
||||
In libtorrent, `set_ssl_certificate()`_ in torrent_handle_ is used to tell libtorrent where
|
||||
In libtorrent, set_ssl_certificate() in torrent_handle is used to tell libtorrent where
|
||||
to find the peer certificate and the private key for it. When an SSL torrent is loaded,
|
||||
the torrent_need_cert_alert_ is posted to remind the user to provide a certificate.
|
||||
the torrent_need_cert_alert is posted to remind the user to provide a certificate.
|
||||
|
||||
A peer connecting to an SSL torrent MUST provide the *SNI* TLS extension (server name
|
||||
indication). The server name is the hex encoded info-hash of the torrent to connect to.
|
||||
|
|
@ -1121,7 +1121,7 @@ This is required for the client accepting the connection to know which certifica
|
|||
present.
|
||||
|
||||
SSL connections are accepted on a separate socket from normal bittorrent connections. To
|
||||
pick which port the SSL socket should bind to, set ``session_settings::ssl_listen`` to a
|
||||
pick which port the SSL socket should bind to, set session_settings::ssl_listen to a
|
||||
different port. It defaults to port 4433. This setting is only taken into account when the
|
||||
normal listen socket is opened (i.e. just changing this setting won't necessarily close
|
||||
and re-open the SSL socket). To not listen on an SSL socket at all, set ``ssl_listen`` to 0.
|
||||
|
|
|
|||
|
|
@ -413,20 +413,18 @@ namespace libtorrent
|
|||
// Or, if you have a raw char buffer::
|
||||
//
|
||||
// const char* buf;
|
||||
// ...
|
||||
// // ...
|
||||
// entry e = bdecode(buf, buf + data_size);
|
||||
//
|
||||
// Now we just need to know how to retrieve information from the entry.
|
||||
//
|
||||
// If ``bdecode()`` encounters invalid encoded data in the range given to it
|
||||
// it will throw libtorrent_exception.
|
||||
template<class OutIt>
|
||||
int bencode(OutIt out, const entry& e)
|
||||
TORRENT_EXPORT template<class OutIt> int bencode(OutIt out, const entry& e)
|
||||
{
|
||||
return detail::bencode_recursive(out, e);
|
||||
}
|
||||
template<class InIt>
|
||||
entry bdecode(InIt start, InIt end)
|
||||
TORRENT_EXPORT template<class InIt> entry bdecode(InIt start, InIt end)
|
||||
{
|
||||
entry e;
|
||||
bool err = false;
|
||||
|
|
@ -437,8 +435,7 @@ namespace libtorrent
|
|||
if (err) return entry();
|
||||
return e;
|
||||
}
|
||||
template<class InIt>
|
||||
entry bdecode(InIt start, InIt end, int& len)
|
||||
TORRENT_EXPORT template<class InIt> entry bdecode(InIt start, InIt end, int& len)
|
||||
{
|
||||
entry e;
|
||||
bool err = false;
|
||||
|
|
|
|||
Loading…
Reference in New Issue