Small documentation fixes

README.asciidoc

@@ -10,15 +10,24 @@ on Python, PyQt5 and QtWebKit and free software, licensed under the GPL.
 
 It was inspired by other browsers/addons like dwb and Vimperator/Pentadactyl.
 
+Documentation
+-------------
+
+In addition to the topics mentioned in that README, the following documents are
+available:
+
 * link:doc/FAQ.asciidoc[Frequently asked questions]
+* link:doc/HACKING.asciidoc[HACKING]
+* link:doc/BUGS[BUGS]
+* link:doc/TODO[TODO]
 
 Getting help
 ------------
 
-Documentation is slowly catching up as this is a rather young project.
+You can get help in the IRC channel
-
+irc://irc.freenode.org/#qutebrowser[`#qutebrowser`] on
-You can however get help in the IRC channel
+http://freenode.net/[Freenode]
-irc://irc.freenode.org/#qutebrowser[#qutebrowser] on Freenode, or by writing a
+(https://webchat.freenode.net/?channels=#qutebrowser[webchat]), or by writing a
 message to the
 https://lists.schokokeks.org/mailman/listinfo.cgi/qutebrowser[mailinglist] at
 mailto:qutebrowser@lists.qutebrowser.org[].
@@ -26,7 +35,7 @@ mailto:qutebrowser@lists.qutebrowser.org[].
 Running qutebrowser
 -------------------
 
-After installing the <<requirements>>, you have these options:
+After installing the <<requirements,requirements>>, you have these options:
 
 * Run qutebrowser directly via `python3 -m qutebrowser`. Note executing
 qutebrowser.py directly as script won't work, as Python won't recognize the
@@ -63,7 +72,8 @@ The following software and libraries are required to run qutebrowser:
 * https://pypi.python.org/pypi/setuptools/[pkg_resources/setuptools]
 * https://github.com/g2p/rfc6266[rfc6266]
 
-The following libraries are optional and provide better debugging:
+The following libraries are optional and provide colored logging in the
+console:
 
 * https://pypi.python.org/pypi/colorlog/[colorlog]
 * On Windows: https://pypi.python.org/pypi/colorama/[colorama]

doc/FAQ.asciidoc

@@ -6,7 +6,7 @@ The Compiler <mail@qutebrowser.org>
 What is qutebrowser based on?::
     qutebrowser uses http://www.python.org/[Python], http://qt-project.org/[Qt]
     and http://www.riverbankcomputing.com/software/pyqt/intro[PyQt].
-    +
++
     The concept of it is largely inspired by
     http://portix.bitbucket.org/dwb/[dwb] and
     http://www.vimperator.org/vimperator[Vimperator]. Many actions and
@@ -17,7 +17,7 @@ Why another browser?::
     happy with, so I started to write my own. Also, I needed a project to get
     into writing GUI applications with Python and
     link:http://qt-project.org/[Qt]/link:http://www.riverbankcomputing.com/software/pyqt/intro[PyQt].
-    +
++
     Read the next few questions to find out why I was unhappy with existing
     software.
 
@@ -27,13 +27,13 @@ What's wrong with link:http://portix.bitbucket.org/dwb/[dwb]/link:http://sourcef
     which causes a lot of crashes. As the GTK API using WebKit1 is
     https://lists.webkit.org/pipermail/webkit-gtk/2014-March/001821.html[deprecated],
     these bugs are never going to be fixed.
-    +
++
     The newer
     http://webkitgtk.org/reference/webkit2gtk/stable/index.html[WebKit2 API]
     seems to lack basic features like proxy support, and almost no projects
     seem to have started porting to WebKit2 (I only know of
     http://www.uzbl.org/[uzbl]).
-    +
++
     qutebrowser uses http://qt-project.org/[Qt] and
     http://qt-project.org/wiki/QtWebKit[QtWebKit] instead, which suffers from
     far less such crashes. It might switch to
@@ -47,7 +47,7 @@ What's wrong with https://www.mozilla.org/en-US/firefox/new/[Firefox] and link:h
     slower and more bloated with every upgrade, and has some
     https://blog.mozilla.org/advancingcontent/2014/02/11/publisher-transformation-with-users-at-the-center/[horrible
     ideas] lately.
-    +
++
     Also, developing addons for it is a nightmare.
 
 What's wrong with http://www.chromium.org/Home[Chromium] and https://vimium.github.io/[Vimium]?::
@@ -76,9 +76,9 @@ Is there an adblocker?::
     https://blog.mozilla.org/nnethercote/2014/05/14/adblock-pluss-effect-on-firefoxs-memory-usage/[RAM
     usage], so implementing it properly might take some time and won't be done
     for v0.1.
-    +
++
     However, there are some alternatives you could use to block ads:
-    +
++
     * You can use a hosts file to block ads. Examples:
       http://someonewhocares.org/hosts/[1],
       http://winhelp2002.mvps.org/hosts.htm[2],
@@ -87,5 +87,6 @@ Is there an adblocker?::
       filter ads before they even get to the browser.
     * Use the https://www.requestpolicy.com/[RequestPolicy] functionality to
       block ads, which currently isn't implemented either.
-    +
++
-    If you think you can add ad blocking or request policy, please contribute!
+    If you think you can add ad blocking or request policy, please
+    link:doc/HACKING.asciidoc[contribute]!

doc/HACKING.asciidoc

@@ -18,11 +18,13 @@ probably change it for you then, though.
 If you have any problems, I'm more than happy to help! You can get help in
 several ways:
 
-* Send a mail to the mailing list at qutebrowser@lists.qutebrowser.org
+* Send a mail to the mailing list at mailto:qutebrowser@lists.qutebrowser.org[]
 (optionally
 https://lists.schokokeks.org/mailman/listinfo.cgi/qutebrowser[subscribe]
 first).
-* Join the IRC channel `#qutebrowser` on http://www.freenode.org/[Freenode].
+* Join the IRC channel irc://irc.freenode.org/#qutebrowser[`#qutebrowser`] on
+http://freenode.net/[Freenode]
+(https://webchat.freenode.net/?channels=#qutebrowser[webchat]).
 
 Finding something to work on
 ----------------------------
@@ -106,7 +108,7 @@ https://docs.python.org/3.4/library/unittest.html[unittest] framework
     - untracked git files
     - whitespace/CRLF problems
     - `set_trace` invocations
-    - VCS conflict markers.
+    - VCS conflict markers
 
 If you changed `setup.py` or `MANIFEST.in`, add the `--setup` argument to run
 the following additional checkers:
@@ -147,10 +149,10 @@ module.
 Debugging
 ~~~~~~~~~
 
-In the `qutebrowser.utils.debug` and `qutebrowser.utils.signal` modules there
+In the `qutebrowser.utils.debug` module there are some useful functions for
-are some useful functions for debugging. In particular you should use
+debugging. In particular you should use `set_trace` from
-`set_trace` from `qutebrowser.utils.debug` instead of `pdb` to set breakpoints
+`qutebrowser.utils.debug` instead of `pdb` to set breakpoints or you'll get
-or you'll get annoying Qt error messages.
+annoying Qt error messages.
 
 When starting qutebrowser with the `--debug` flag you also get useful debug
 logs. You can add +--logfilter _category[,category,...]_+ to restrict logging
@@ -170,8 +172,6 @@ Some resources which might be handy:
 * https://docs.python.org/3/library/index.html[The Python reference]
 * http://httpbin.org/[httpbin, a test service for HTTP requests/responses]
 * http://requestb.in/[RequestBin, a service to inspect HTTP requests]
-* http://greenbytes.de/tech/tc2231/[Test cases for the `Content-Disposition`
-header]
 
 Hints
 -----
@@ -185,7 +185,7 @@ available.
 In qutebrowser, the policy is usually using the Python libraries, as they
 provide exceptions and other benefits.
 
-There are some exceptions for that:
+There are some exceptions to that:
 
 * `QThread` is used instead of Python threads because it provides signals and
 slots.