doc: readme: fix whitespaces and markup

add links to packages

Signed-off-by: Sebastian Wagner <sebix@sebix.at>

1 files changed, 146 insertions, 144 deletions

diff --git a/README.md b/README.md
index 99b92cb..d8c4cde 100644
--- a/README.md
+++ b/README.md
@@ -4,27 +4,32 @@ dnspython [![Build Status](https://travis-ci.org/rthalley/dnspython.svg?branch=m
 
 dnspython is a DNS toolkit for Python. It supports almost all record
 types. It can be used for queries, zone transfers, and dynamic
-updates.  It supports TSIG authenticated messages and EDNS0.
+updates. It supports TSIG authenticated messages and EDNS0.
 
 dnspython provides both high and low level access to DNS. The high
 level classes perform queries for data of a given name, type, and
-class, and return an answer set.  The low level classes allow direct
+class, and return an answer set. The low level classes allow direct
 manipulation of DNS zones, messages, names, and records.
 
 To see a few of the ways dnspython can be used, look in the examples/
 directory.
 
 dnspython originated at Nominum where it was developed to facilitate
-the testing of DNS software.  Nominum has generously allowed it to be
+the testing of DNS software. Nominum has generously allowed it to be
 open sourced under a BSD-style license, and helps support its future
 development by continuing to employ the author :).
 
 ## INSTALLATION
-- If you have pip installed,  you can do this
+- If you have pip installed, you can do this
 `pip install dnspython`
 - If not just download the source file and unzip it, then run this
 `sudo python setup.py install`
 
+Packages are available for some distributions:
+ * [Ubuntu](http://packages.ubuntu.com/search?keywords=dnspython&searchon=names&suite=xenial&section=all)
+ * [Debian](https://packages.debian.org/search?keywords=dnspython&searchon=names&suite=stable&section=all)
+ * OpenSUSE: [py2](https://software.opensuse.org/package/python-dnspython), [py3](https://software.opensuse.org/package/python3-dnspython)
+
 ## ABOUT THIS RELEASE
 
 This is dnspython 1.14.0
@@ -33,14 +38,14 @@ New since 1.13.0:
 
 	CSYNC RRs are now supported.
 
-	dns/message.py (make_query): Setting any value which implies
-	EDNS will turn on EDNS if 'use_edns' has not been specified.
+	`dns/message.py` (`make_query`): Setting any value which implies
+	EDNS will turn on EDNS if `use_edns` has not been specified.
 
 Bugs fixed since 1.13.0:
 
 	TSIG signature algorithm setting was broken by the Python 2
 	and Python 3 code line merge.
-	  
+
 	A bug in the LOC RR destroyed N/S and E/W distinctions within
 	a degree of the equator or prime merdian respectively.
 
@@ -51,15 +56,15 @@ Bugs fixed since 1.13.0:
 	Running with python optimization on caused issues when
 	stripped docstrings were referenced. [issue #154]
 
-	dns.zone.from_text() erroneously required the zone to be provided.
+	`dns.zone.from_text()` erroneously required the zone to be provided.
 	[issue #153]
 
 New since 1.12.0:
 
 	Dnspython now uses a single source for Python 2 and Python 3,
 	eliminating the painful merging between the Python 2 and Python 3
-	branches.  Thank you so much to Arthur Gautier for taking on this
-	challenge and making it work!  It was a big job!
+	branches. Thank you so much to Arthur Gautier for taking on this
+	challenge and making it work! It was a big job!
 
 	Support for Python older than 2.6 dropped.
 
@@ -80,19 +85,19 @@ New since 1.12.0:
 
 Bugs fixed since 1.12.0:
 
-    A number of Unicode name bugs have been fixed.
+	A number of Unicode name bugs have been fixed.
 
-	resolv.conf processing now rejects lines with too few tokens.
+	`resolv.conf` processing now rejects lines with too few tokens.
 
 	NameDicts now keep the max-depth value correct, and update properly.
 
 New since 1.11.1:
-    
-	Added dns.zone.to_text().
 
-	Added support for "options rotate" in /etc/resolv.conf.
+	Added `dns.zone.to_text()`.
+
+	Added support for "options rotate" in `/etc/resolv.conf`.
 
-	dns.rdtypes.ANY.DNSKEY now has helpers functions to convert
+	`dns.rdtypes.ANY.DNSKEY` now has helpers functions to convert
 	between the numeric form of the flags and a set of
 	human-friendly strings
 
@@ -108,13 +113,13 @@ Bugs fixed since 1.11.1:
 
 	dnspython raised an exception when reading a masterfile starting
 	with leading whitespace
-	
+
 	dnspython was affected by a python slicing API bug present on
 	64-bit windows.
 
 	Unicode escaping was applied at the wrong time.
 
-	RRSIG to_text() did not respect the relativize setting.
+	RRSIG `to_text()` did not respect the relativize setting.
 
 	APL RRs with zero rdlength were rejected.
 
@@ -125,29 +130,29 @@ Bugs fixed since 1.11.1:
 	The IXFR state machine didn't handle long IXFR diffs.
 
 New since 1.11.0:
-    
+
 	Nothing
 
 Bugs fixed since 1.11.0:
 
-	dns.resolver.Resolver erroneously referred to 'retry_servfail'
-	instead of 'self.retry_servfail'.
+	`dns.resolver.Resolver` erroneously referred to `retry_servfail`
+	instead of `self.retry_servfail`.
 
-     	dns.tsigkeyring.to_text() would fail trying to convert the
-     	keyname to text.
+		dns.tsigkeyring.to_text() would fail trying to convert the
+		keyname to text.
 
 	Multi-message TSIGs were broken for algorithms other than
 	HMAC-MD5 because we weren't passing the right digest module to
 	the HMAC code.
 
-	dns.dnssec._find_candidate_keys() tried to extract the key
+	`dns.dnssec._find_candidate_keys()` tried to extract the key
 	from the wrong variable name.
 
 	$GENERATE tests were not backward compatible with python 2.4.
 
 New since 1.10.0:
-    
-        $GENERATE support
+
+		$GENERATE support
 
 	TLSA RR support
 
@@ -155,8 +160,7 @@ New since 1.10.0:
 
 Bugs fixed since 1.10.0:
 
-        Names with offsets >= 2^14 are no longer added to the compression
-	table.
+	Names with offsets >= 2^14 are no longer added to the compression table.
 
 	The "::" syntax is not used to shorten a single 16-bit section of
 	the text form an IPv6 address.
@@ -171,14 +175,14 @@ Bugs fixed since 1.10.0:
 
 New since 1.9.4:
 
-       	Added dns.resolver.LRUCache.  In this cache implementation,
+	Added dns.resolver.LRUCache. In this cache implementation,
 	the cache size is limited to a user-specified number of nodes,
 	and when adding a new node to a full cache the least-recently
-	used node is removed.  If you're crawling the web or otherwise
+	used node is removed. If you're crawling the web or otherwise
 	doing lots of resolutions and you are using a cache, switching
 	to the LRUCache is recommended.
 
-	dns.resolver.query() will try TCP if a UDP response is
+	`dns.resolver.query()` will try TCP if a UDP response is
 	truncated.
 
 	The python socket module's DNS methods can be now be overridden
@@ -188,17 +192,17 @@ New since 1.9.4:
 
 	Whitespace is allowed in SSHFP fingerprints.
 
-	Origin checking in dns.zone.from_xfr() can be disabled.
+	Origin checking in `dns.zone.from_xfr()` can be disabled.
 
 	Trailing junk checking can be disabled.
 
 	A source port can be specified when creating a resolver query.
 
-	All EDNS values may now be specified to dns.message.make_query().
+	All EDNS values may now be specified to `dns.message.make_query()`.
 
 Bugs fixed since 1.9.4:
 
-     	IPv4 and IPv6 address processing is now stricter.
+	IPv4 and IPv6 address processing is now stricter.
 
 	Bounds checking of slices in rdata wire processing is now more
 	strict, and bounds errors (e.g. we got less data than was
@@ -211,111 +215,110 @@ Bugs fixed since 1.9.4:
 
 New since 1.9.3:
 
-        Nothing.
+	Nothing.
 
 Bugs fixed since 1.9.3:
 
-     	The rdata _wire_cmp() routine now handles relative names.
+	The rdata `_wire_cmp()` routine now handles relative names.
 
-	The SIG RR implementation was missing 'import struct'.
+	The SIG RR implementation was missing `import struct`.
 
 New since 1.9.2:
 
-    	A boolean parameter, 'raise_on_no_answer', has been added to
-	the query() methods.  In no-error, no-data situations, this
-	parameter determines whether NoAnswer should be raised or not.
-	If True, NoAnswer is raised.  If False, then an Answer()
+	A boolean parameter, `raise_on_no_answer`, has been added to
+	the `query()` methods. In no-error, no-data situations, this
+	parameter determines whether `NoAnswer` should be raised or not.
+	If True, `NoAnswer` is raised. If False, then an `Answer()`
 	object with a None rrset will be returned.
 
-	Resolver Answer() objects now have a canonical_name field.
+	Resolver `Answer()` objects now have a canonical_name field.
 
-	Rdata now have a __hash__ method.
+	Rdata now has a `__hash__` method.
 
 Bugs fixed since 1.9.2:
 
-       	Dnspython was erroneously doing case-insensitive comparisons
+	Dnspython was erroneously doing case-insensitive comparisons
 	of the names in NSEC and RRSIG RRs.
 
-	We now use "is" and not "==" when testing what section an RR
-	is in.
+	We now use `is` and not `==` when testing what section an RR is in.
 
 	The resolver now disallows metaqueries.
 
 New since 1.9.1:
 
-    	Nothing.
+	Nothing.
 
 Bugs fixed since 1.9.1:
 
-	The dns.dnssec module didn't work at all due to missing
+	The `dns.dnssec` module didn't work at all due to missing
 	imports that escaped detection in testing because the test
-	suite also did the imports.  The third time is the charm!
+	suite also did the imports. The third time is the charm!
 
 New since 1.9.0:
 
-    	Nothing.
+	Nothing.
 
 Bugs fixed since 1.9.0:
 
-        The dns.dnssec module didn't work with DSA due to namespace
+	The `dns.dnssec` module didn't work with DSA due to namespace
 	contamination from a "from"-style import.
 
 New since 1.8.0:
 
-    	dnspython now uses poll() instead of select() when available.
+	dnspython now uses `poll()` instead of `select()` when available.
 
-	Basic DNSSEC validation can be done using dns.dnsec.validate()
-	and dns.dnssec.validate_rrsig() if you have PyCrypto 2.3 or
-	later installed.  Complete secure resolution is not yet
+	Basic DNSSEC validation can be done using `dns.dnsec.validate()`
+	and `dns.dnssec.validate_rrsig()` if you have PyCrypto 2.3 or
+	later installed. Complete secure resolution is not yet
 	available.
 
-	Added key_id() to the DNSSEC module, which computes the DNSSEC
+	Added `key_id()` to the DNSSEC module, which computes the DNSSEC
 	key id of a DNSKEY rdata.
 
-	Added make_ds() to the DNSSEC module, which returns the DS RR
+	Added `make_ds()` to the DNSSEC module, which returns the DS RR
 	for a given DNSKEY rdata.
 
 	dnspython now raises an exception if HMAC-SHA284 or
-	HMAC-SHA512 are used with a Python older than 2.5.2.  (Older
+	HMAC-SHA512 are used with a Python older than 2.5.2. (Older
 	Pythons do not compute the correct value.)
 
 	Symbolic constants are now available for TSIG algorithm names.
 
 Bugs fixed since 1.8.0
 
-        dns.resolver.zone_for_name() didn't handle a query response
+	`dns.resolver.zone_for_name()` didn't handle a query response
 	with a CNAME or DNAME correctly in some cases.
 
-        When specifying rdata types and classes as text, Unicode
+	When specifying rdata types and classes as text, Unicode
 	strings may now be used.
 
 	Hashlib compatibility issues have been fixed.
 
-	dns.message now imports dns.edns.
+	`dns.message` now imports `dns.edns`.
 
 	The TSIG algorithm value was passed incorrectly to use_tsig()
 	in some cases.
 
 New since 1.7.1:
 
-    	Support for hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384
+	Support for hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384
 	and hmac-sha512 has been contributed by Kevin Chen.
 
-	The tokenizer's tokens are now Token objects instead of (type,
-	value) tuples.
+	The tokenizer's tokens are now Token objects instead of (type, value)
+	tuples.
 
 Bugs fixed since 1.7.1:
 
-        Escapes in masterfiles now work correctly.  Previously they
+	Escapes in masterfiles now work correctly. Previously they
 	were only working correctly when the text involved was part of
 	a domain name.
 
-     	When constructing a DDNS update, if the present() method was
+	When constructing a DDNS update, if the `present()` method was
 	used with a single rdata, a zero TTL was not added.
 
 	The entropy pool needed locking to be thread safe.
 
-	The entropy pool's reading of /dev/random could cause
+	The entropy pool's reading of `/dev/random` could cause
 	dnspython to block.
 
 	The entropy pool did buffered reads, potentially consuming more
@@ -331,18 +334,18 @@ Bugs fixed since 1.7.1:
 
 New since 1.7.0:
 
-    	Nothing
+	Nothing
 
 Bugs fixed since 1.7.0:
 
-     	The 1.7.0 kitting process inadvertently omitted the code for the
+	The 1.7.0 kitting process inadvertently omitted the code for the
 	DLV RR.
 
 	Negative DDNS prerequisites are now handled correctly.
 
 New since 1.6.0:
 
-    	Rdatas now have a to_digestable() method, which returns the
+	Rdatas now have a `to_digestable()` method, which returns the
 	DNSSEC canonical form of the rdata, suitable for use in
 	signature computations.
 
@@ -354,24 +357,24 @@ New since 1.6.0:
 
 	UDP IXFR is now supported.
 
-	The wire format parser now has a 'one_rr_per_rrset' mode, which
+	The wire format parser now has a `one_rr_per_rrset` mode, which
 	suppresses the usual coalescing of all RRs of a given type into a
 	single RRset.
 
 	Various helpful DNSSEC-related constants are now defined.
 
-	The resolver's query() method now has an optional 'source' parameter,
-        allowing the source IP address to be specified.
+	The resolver's `query()` method now has an optional `source` parameter,
+	allowing the source IP address to be specified.
 
 Bugs fixed since 1.6.0:
 
-     	On Windows, the resolver set the domain incorrectly.
+	On Windows, the resolver set the domain incorrectly.
 
 	DS RR parsing only allowed one Base64 chunk.
 
 	TSIG validation didn't always use absolute names.
 
-	NSEC.to_text() only printed the last window.
+	`NSEC.to_text()` only printed the last window.
 
 	We did not canonicalize IPv6 addresses before comparing them; we
 	would thus treat equivalent but different textual forms, e.g.
@@ -386,9 +389,9 @@ New since 1.5.0:
 	Added dns.inet.is_multicast().
 
 Bugs fixed since 1.5.0:
-	
-	If select() raises an exception due to EINTR, we should just
-	select() again.
+
+	If `select()` raises an exception due to EINTR, we should just
+	`select()` again.
 
 	If the queried address is a multicast address, then don't
 	check that the address of the response is the same as the
@@ -402,66 +405,66 @@ Bugs fixed since 1.5.0:
 
 New since 1.4.0:
 
-    	Answer objects now support more of the python sequence
+	Answer objects now support more of the python sequence
 	protocol, forwarding the requests to the answer rrset.
-	E.g. "for a in answer" is equivalent to "for a in
-	answer.rrset", "answer[i]" is equivalent to "answer.rrset[i]",
-	and "answer[i:j]" is equivalent to "answer.rrset[i:j]".
+	E.g. `for a in answer` is equivalent to `for a in  answer.rrset`,
+	`answer[i]` is equivalent to `answer.rrset[i]`, and and `answer[i:j]` is
+	equivalent to `answer.rrset[i:j]`.
 
 	Making requests using EDNS, including indicating DNSSEC awareness,
-	is now easier.  For example, you can now say:
+	is now easier. For example, you can now say:
 
-	   q = dns.message.make_query('www.dnspython.org', 'MX',
-				      want_dnssec=True)
+	    q = dns.message.make_query('www.dnspython.org', 'MX',
+	    want_dnssec=True)
 
-	dns.query.xfr() can now be used for IXFR.
+	`dns.query.xfr()` can now be used for IXFR.
 
 	Support has been added for the DHCID, IPSECKEY, and SPF RR types.
 
 	UDP messages from unexpected sources can now be ignored by
-	setting ignore_unexpected to True when calling dns.query.udp.
+	setting `ignore_unexpected` to True when calling `dns.query.udp`.
 
 Bugs fixed since 1.4.0:
 
-        If /etc/resolv.conf didn't exist, we raised an exception
+	If `/etc/resolv.conf` didn't exist, we raised an exception
 	instead of simply using the default resolver configuration.
 
-	In dns.resolver.Resolver._config_win32_fromkey(), we were
-	passing the wrong variable to self._config_win32_search().
+	In `dns.resolver.Resolver._config_win32_fromkey()`, we were
+	passing the wrong variable to `self._config_win32_search()`.
 
 New since 1.3.5:
 
-        You can now convert E.164 numbers to/from their ENUM name
-        forms:
+	You can now convert E.164 numbers to/from their ENUM name
+	forms:
 
-	      >>> import dns.e164
-	      >>> n = dns.e164.from_e164("+1 555 1212")
-	      >>> n
-	      <DNS name 2.1.2.1.5.5.5.1.e164.arpa.>
-	      >>> dns.e164.to_e164(n)
-	      '+15551212'
+	    >>> import dns.e164
+	    >>> n = dns.e164.from_e164("+1 555 1212")
+	    >>> n
+	    <DNS name 2.1.2.1.5.5.5.1.e164.arpa.>
+	    >>> dns.e164.to_e164(n)
+	    '+15551212'
 
 	You can now convert IPv4 and IPv6 address to/from their
 	corresponding DNS reverse map names:
 
-	      >>> import dns.reversename
-	      >>> n = dns.reversename.from_address("127.0.0.1")
-	      >>> n
-	      <DNS name 1.0.0.127.in-addr.arpa.>
-	      >>> dns.reversename.to_address(n)
-	      '127.0.0.1'
+	    >>> import dns.reversename
+	    >>> n = dns.reversename.from_address("127.0.0.1")
+	    >>> n
+	    <DNS name 1.0.0.127.in-addr.arpa.>
+	    >>> dns.reversename.to_address(n)
+	    '127.0.0.1'
 
 	You can now convert between Unicode strings and their IDN ACE
 	form:
 
-	      >>> n = dns.name.from_text(u'les-\u00e9l\u00e8ves.example.')
-	      >>> n
-	      <DNS name xn--les-lves-50ai.example.>
-	      >>> n.to_unicode()
-	      u'les-\xe9l\xe8ves.example.'
+	    >>> n = dns.name.from_text(u'les-\u00e9l\u00e8ves.example.')
+	    >>> n
+	    <DNS name xn--les-lves-50ai.example.>
+	    >>> n.to_unicode()
+	    u'les-\xe9l\xe8ves.example.'
 
-	The origin parameter to dns.zone.from_text() and dns.zone.to_text()
-	is now optional.  If not specified, the origin will be taken from
+	The origin parameter to `dns.zone.from_text()` and `dns.zone.to_text()`
+	is now optional. If not specified, the origin will be taken from
 	the first $ORIGIN statement in the master file.
 
 	Sanity checking of a zone can be disabled; this is useful when
@@ -469,12 +472,12 @@ New since 1.3.5:
 
 Bugs fixed since 1.3.5:
 
-     	The correct delimiter was not used when retrieving the
+	The correct delimiter was not used when retrieving the
 	list of nameservers from the registry in certain versions of
 	windows.
 
-        The floating-point version of latitude and longitude in LOC RRs
-	(float_latitude and float_longitude) had incorrect signs for
+	The floating-point version of latitude and longitude in LOC RRs
+	(`float_latitude` and `float_longitude`) had incorrect signs for
 	south latitudes and west longitudes.
 
 	BIND 8 TTL syntax is now accepted in all TTL-like places (i.e.
@@ -486,39 +489,38 @@ Bugs fixed since 1.3.5:
 
 New since 1.3.4:
 
-     	In the resolver, if time goes backward a little bit, ignore
-    	it.
+	In the resolver, if time goes backward a little bit, ignore
+	it.
 
-	zone_for_name() has been added to the resolver module.  It
+	`zone_for_name()` has been added to the resolver module. It
 	returns the zone which is authoritative for the specified
-	name, which is handy for dynamic update.  E.g.
+	name, which is handy for dynamic update. E.g.
 
-	      import dns.resolver
-	      print dns.resolver.zone_for_name('www.dnspython.org')
+	    import dns.resolver
+	    print dns.resolver.zone_for_name('www.dnspython.org')
 
-	will output "dnspython.org." and
+	will output `"dnspython.org."` and
 
-	      print dns.resolver.zone_for_name('a.b.c.d.e.f.example.')
+	    print dns.resolver.zone_for_name('a.b.c.d.e.f.example.')
 
 	will output ".".
 
-	The default resolver can be fetched with the
-	get_default_resolver() method.
+	The `default resolver` can be fetched with the
+	`get_default_resolver()` method.
 
-    	You can now get the parent (immediate superdomain) of a name
-	by using the parent() method.
+	You can now get the parent (immediate superdomain) of a name
+	by using the `parent()` method.
 
-	Zone.iterate_rdatasets() and Zone.iterate_rdatas() now have
-	a default rdtype of dns.rdatatype.ANY like the documentation
-	says.
+	`Zone.iterate_rdatasets()` and `Zone.iterate_rdatas()` now have a default
+	rdtype of `dns.rdatatype.ANY` like the documentation says.
 
 	A Dynamic DNS example, ddns.py, has been added.
 
 New since 1.3.3:
 
 	The source address and port may now be specified when calling
-	dns.query.{udp,tcp,xfr}.
-	
+	`dns.query.{udp,tcp,xfr}`.
+
 	The resolver now does exponential backoff each time it runs
 	through all of the nameservers.
 
@@ -528,23 +530,23 @@ New since 1.3.3:
 
 New since 1.3.2:
 
-    	dns.message.Message.find_rrset() now uses an index, vastly
-	improving the from_wire() performance of large messages such
+	`dns.message.Message.find_rrset()` now uses an index, vastly
+	improving the `from_wire()` performance of large messages such
 	as zone transfers.
 
-	Added dns.message.make_response(), which creates a skeletal
+	Added `dns.message.make_response()`, which creates a skeletal
 	response for the specified query.
 
-	Added opcode() and set_opcode() convenience methods to the
-	dns.message.Message class.  Added the request_payload
+	Added `opcode()` and `set_opcode()` convenience methods to the
+	dns.message.Message class. Added the `request_payload`
 	attribute to the Message class.
 
-        The 'file' parameter of dns.name.Name.to_wire() is now
+	The `file` parameter of `dns.name.Name.to_wire()` is now
 	optional; if omitted, the wire form will be returned as the
 	value of the function.
 
-	dns.zone.from_xfr() in relativization mode incorrectly set
-	zone.origin to the empty name.
+	`dns.zone.from_xfr()` in relativization mode incorrectly set
+	`zone.origin` to the empty name.
 
 	The masterfile parser incorrectly rejected TXT records where a
 	value was not quoted.
@@ -552,10 +554,10 @@ New since 1.3.2:
 New since 1.3.1:
 
 	The NSEC format doesn't allow specifying types by number, so
-	we shouldn't either.  (Using the unknown type format is still
+	we shouldn't either. (Using the unknown type format is still
 	OK though.)
 
-	The resolver wasn't catching dns.exception.Timeout, so a timeout
+	The resolver wasn't catching `dns.exception.Timeout`, so a timeout
 	erroneously caused the whole resolution to fail instead of just
 	going on to the next server.
 
@@ -563,7 +565,7 @@ New since 1.3.1:
 	to be raised if a query id wasn't provided when a Renderer was
 	created.
 
-        The conversion of LOC milliseconds values from text to binary was
+	The conversion of LOC milliseconds values from text to binary was
 	incorrect if the length of the milliseconds string was not 3.
 
 New since 1.3.0:
@@ -596,7 +598,7 @@ dnspython home page at
 
 ## DOCUMENTATION
 
-Documentation is sparse at the moment.  Use pydoc, or read the HTML
+Documentation is sparse at the moment. Use pydoc, or read the HTML
 documentation at the dnspython home page, or download the HTML
 documentation.
 
@@ -608,5 +610,5 @@ Bug reports may be sent to bugs@dnspython.org
 
 ## MAILING LISTS
 
-A number of mailing lists are available.  Visit the dnspython home
+A number of mailing lists are available. Visit the dnspython home
 page to subscribe or unsubscribe.