Documentation update

5 files changed, 73 insertions, 6 deletions

diff --git a/doc/source/misc/correct.rst b/doc/source/misc/correct.rst
index a5d7a9c7..61100634 100644
--- a/doc/source/misc/correct.rst
+++ b/doc/source/misc/correct.rst
@@ -14,7 +14,7 @@ The **9** here represents the number of times this message has been corrected.
 
 
 You can show the revisions of a message by loading the
-*display_corrections* plugin, and you
+:ref:`displaycorrections-plugin` plugin, and you
 can correct your own messages with the :term:`/correct` command.
 
 
diff --git a/doc/source/misc/index.rst b/doc/source/misc/index.rst
index 182f35c3..08349437 100644
--- a/doc/source/misc/index.rst
+++ b/doc/source/misc/index.rst
@@ -11,4 +11,5 @@ Contents:
     personal_events
     separate
     ssl
+    troubleshooting
 
diff --git a/doc/source/misc/personal_events.rst b/doc/source/misc/personal_events.rst
index 37a388ad..32cda72b 100644
--- a/doc/source/misc/personal_events.rst
+++ b/doc/source/misc/personal_events.rst
@@ -1,7 +1,7 @@
 Personal Events
 ===============
 
-Starting from poezio 0.8, poezo now supports `user mood`_, `user activity`_,
+Starting from poezio 0.8, poezio now supports `user mood`_, `user activity`_,
 `user tune`_, and `user gaming`_.
 
 Those extensions are standardized ways to broadcast informations that might be
diff --git a/doc/source/misc/ssl.rst b/doc/source/misc/ssl.rst
index f4995f3f..0f7ecd52 100644
--- a/doc/source/misc/ssl.rst
+++ b/doc/source/misc/ssl.rst
@@ -1,9 +1,24 @@
-TLS Management
-==============
+TLS in poezio
+=============
+
+.. _security settings:
 
 Security of the connection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Enabling or disabling TLS
+-------------------------
+
+Starting from version 0.8, poezio is configured to reject unencrypted connections
+by default, in accordance to the `TLS manifesto`_. Users can still allow
+unencrypted connections by setting the :term:`force_encryption` option to false.
+
+If you cannot connect to your server, maybe it does not allow encrypted connections,
+in which case you should reconfigure it if it is yours, or contact your admin
+to let him know he should try to protect your privacy and credentials, at least
+a little.
+
+
 .. _ciphers:
 
 Ciphers
@@ -23,8 +38,8 @@ case, you should notify the administrator that his XMPP server configuration
 is probably not great), or if you want to be even more restrictive (only allowing
 256 bits of security *and* forward secrecy, for example).
 
-Cert valididty
-~~~~~~~~~~~~~~
+Certificate validation
+~~~~~~~~~~~~~~~~~~~~~~
 
 Starting from version 0.7.5, poezio offers some options to check the validity
 of a X.509 certificate.
@@ -84,3 +99,4 @@ can set the :term:`ignore_certificate` value to true, and let the
 .. _Forward Secrecy: https://en.wikipedia.org/wiki/Forward_secrecy
 .. _TOFU/TUFU: https://en.wikipedia.org/wiki/User:Dotdotike/Trust_Upon_First_Use
 .. _PEM format: https://tools.ietf.org/html/rfc1422.html
+.. _TLS manifesto: https://github.com/stpeter/manifesto/blob/master/manifesto.txt
diff --git a/doc/source/misc/troubleshooting.rst b/doc/source/misc/troubleshooting.rst
new file mode 100644
index 00000000..ae2494d2
--- /dev/null
+++ b/doc/source/misc/troubleshooting.rst
@@ -0,0 +1,50 @@
+Troubleshooting
+===============
+
+I cannot connect.
+-----------------
+
+1. Check that you are still connected to the internet.
+2. Double-check your credentials.
+3. Check the :ref:`security settings <security settings>`, maybe your server does not support encryption, or only with weak parameters.
+4. Maybe your DNS are wrong, try setting the :term:`custom_host` option with the server IP.
+5. Overzealous firewall?
+6. Running poezio with -d file.txt (debug mode) might reveal your issues.
+7. Come see us from the `web client`_ to discuss your issues further.
+
+
+The outline of poezio is not displayed and unicode characters are broken
+------------------------------------------------------------------------
+We believe we (or unrelated people) have reported the bug of python3 compiled against the wrong
+ncurses to every_ significant_ distribution_ `out there`_, but if there is still
+one with it, please go ahead and report it.
+
+Poezio tracebacks with weird encoding errors
+--------------------------------------------
+Please check your locale for utf-8 compatibility.
+
+Reconnecting sucks
+------------------
+We know.
+
+Some weird graphical glitches appear once in a blue moon and go away after a refresh
+------------------------------------------------------------------------------------
+We know.
+
+Python is too heavy
+-------------------
+We know. It’s too late to change that. If you are running your XMPP client on a toaster,
+please try mcabber_.
+
+
+Other issues
+------------
+Some things may appear in ``$XDG_DATA_HOME/poezio/errors.log``.
+
+
+.. _web client: https://jappix.com/?r=poezio@muc.poezio.eu
+.. _mcabber: http://mcabber.com/
+.. _every: https://bugs.mageia.org/show_bug.cgi?id=2156
+.. _significant: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=602720
+.. _distribution: https://bugzilla.redhat.com/show_bug.cgi?id=539917
+.. _out there: https://bugs.launchpad.net/ubuntu/+source/python3.2/+bug/789732