From 77811e91b4bb78e25ab6b9c7de04586bf3c784f3 Mon Sep 17 00:00:00 2001
From: mathieui <mathieui@mathieui.net>
Date: Fri, 14 Feb 2014 01:37:18 +0100
Subject: Documentation update
---
doc/source/misc/correct.rst | 2 +-
doc/source/misc/index.rst | 1 +
doc/source/misc/personal_events.rst | 2 +-
doc/source/misc/ssl.rst | 24 +++++++++++++++---
doc/source/misc/troubleshooting.rst | 50 +++++++++++++++++++++++++++++++++++++
5 files changed, 73 insertions(+), 6 deletions(-)
create mode 100644 doc/source/misc/troubleshooting.rst
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
--
cgit v1.2.3