From 11c4e287697d645de7f4226b66abf9d8546f880e Mon Sep 17 00:00:00 2001 From: Florian Bruhin Date: Wed, 23 Jul 2014 20:17:08 +0200 Subject: [PATCH] Small documentation fixes --- README.asciidoc | 22 ++++++++++++++++------ doc/FAQ.asciidoc | 19 ++++++++++--------- doc/HACKING.asciidoc | 20 ++++++++++---------- 3 files changed, 36 insertions(+), 25 deletions(-) diff --git a/README.asciidoc b/README.asciidoc index 90828068a..edf09add1 100644 --- a/README.asciidoc +++ b/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 however get help in the IRC channel -irc://irc.freenode.org/#qutebrowser[#qutebrowser] on Freenode, or by writing a +You can get help in the IRC channel +irc://irc.freenode.org/#qutebrowser[`#qutebrowser`] on +http://freenode.net/[Freenode] +(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 <>, you have these options: +After installing the <>, 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] diff --git a/doc/FAQ.asciidoc b/doc/FAQ.asciidoc index 59833eac3..eb856d40d 100644 --- a/doc/FAQ.asciidoc +++ b/doc/FAQ.asciidoc @@ -6,7 +6,7 @@ The Compiler 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]! diff --git a/doc/HACKING.asciidoc b/doc/HACKING.asciidoc index 374907bc6..9dd8bf942 100644 --- a/doc/HACKING.asciidoc +++ b/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 -are some useful functions for debugging. In particular you should use -`set_trace` from `qutebrowser.utils.debug` instead of `pdb` to set breakpoints -or you'll get annoying Qt error messages. +In the `qutebrowser.utils.debug` module there are some useful functions for +debugging. In particular you should use `set_trace` from +`qutebrowser.utils.debug` instead of `pdb` to set breakpoints or you'll get +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.