Add an initial user manual for converse.js
BIN
docs/source/images/add-contact.png
Normal file
After Width: | Height: | Size: 9.8 KiB |
BIN
docs/source/images/homepage.jpg
Normal file
After Width: | Height: | Size: 34 KiB |
BIN
docs/source/images/pending-contact.jpg
Normal file
After Width: | Height: | Size: 14 KiB |
BIN
docs/source/images/register-form.jpg
Normal file
After Width: | Height: | Size: 28 KiB |
BIN
docs/source/images/register-panel.jpg
Normal file
After Width: | Height: | Size: 18 KiB |
BIN
docs/source/images/remove-contact.png
Normal file
After Width: | Height: | Size: 13 KiB |
BIN
docs/source/images/remove_contact.png
Normal file
After Width: | Height: | Size: 12 KiB |
BIN
docs/source/images/ungrouped-contact.png
Normal file
After Width: | Height: | Size: 9.1 KiB |
@ -13,6 +13,8 @@ Preface
|
||||
This is the official documentation for Converse.js. If you'd like to
|
||||
contribute, please read the :doc:`documentation` page.
|
||||
|
||||
You might instead be looking for the `User Manual <manual.html>`_.
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
@ -46,3 +48,4 @@ Table of Contents
|
||||
translations
|
||||
documentation
|
||||
builds
|
||||
|
||||
|
186
docs/source/manual.rst
Normal file
@ -0,0 +1,186 @@
|
||||
===========================
|
||||
The Converse.js User Manual
|
||||
===========================
|
||||
|
||||
.. |br| raw:: html
|
||||
|
||||
<br />
|
||||
|
||||
.. contents:: Table of Contents
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
.. figure:: images/homepage.jpg
|
||||
:align: right
|
||||
:alt: The converse.js website
|
||||
|
||||
The converse.js website
|
||||
|
||||
**Welcome to the converse.js user manual**. This manual is very much still a work
|
||||
in progress and is far from complete. Please bear in mind that it's the work of volunteers.
|
||||
|
||||
If you have requests or suggestions on how the manual can be improved or
|
||||
expanded, then please `contact me <https://opkode.com/contact.html>`_
|
||||
or create a new ticket on `Github <https://github.com/jcbrand/converse.js/issues>`_.
|
||||
|
||||
Although converse.js can be integrated into any website, for this user manual
|
||||
we'll refer to the canonical version at https://conversejs.org.
|
||||
|
||||
This documentation also integrates the converse.js chat client, so you can try
|
||||
out some of the steps right on this page! Just click the **Toggle chat** button
|
||||
at the bottom right of the page to open the so-called *control box* of the
|
||||
converse.js chat client.
|
||||
|
||||
Registering a new chat account
|
||||
==============================
|
||||
|
||||
.. figure:: images/register-panel.jpg
|
||||
:align: left
|
||||
:alt: The registration panel of the converse.js control box.
|
||||
|
||||
The registration panel of converse.js
|
||||
|
||||
With converse.js you can register a new XMPP account on any publically available XMPP provider.
|
||||
To do so, click the **Register** tab on the chat client.
|
||||
|
||||
You will then see the *registration panel* as shown in the picture below.
|
||||
|
||||
Choosing your provider
|
||||
----------------------
|
||||
|
||||
Converse.js uses a chat protocol called XMPP (also known as Jabber) which allows "federation".
|
||||
This means that it's similar to email, in the sense that people signed in at
|
||||
different XMPP chat providers can still chat with one another.
|
||||
|
||||
For example, if you have a Yahoo! email account, you can send and receive emails from
|
||||
a friend with a Google email account. In the same way, if you have a chat
|
||||
account from **Conversejs.org**, you can send and receive chat messages with a
|
||||
friend who has an account at `Jappix.com <https://jappix.com>`_.
|
||||
|
||||
There are many free providers online which allow you to register a new account.
|
||||
You can see a list of some of them at `xmpp.net <https://xmpp.net/directory.php>`_.
|
||||
The `xmpp.net <https://xmpp.net/directory.php>`_ website provides a security grading
|
||||
for the XMPP servers of the providers, which is very useful. They are however sometimes
|
||||
slow to add new servers to the list.
|
||||
A larger list of XMPP providers is also available at `list.jabber.net <https://list.jabber.at/>`_.
|
||||
|
||||
You can find the domain name for a server under the *Domain* column at
|
||||
`xmpp.net <https://xmpp.net/directory.php>`_. or the *Server* column at
|
||||
`list.jabber.net <https://list.jabber.at/>`_.
|
||||
|
||||
Once you know which XMPP provider you'd like to use, you can type its domain
|
||||
name and click the **Fetch registration form** button.
|
||||
|
||||
|br|
|
||||
|
||||
.. figure:: images/register-form.jpg
|
||||
:align: left
|
||||
:alt: The registration form for an XMPP account at conversejs.org
|
||||
|
||||
The registration form
|
||||
|
||||
|
||||
Filling out the registration form
|
||||
---------------------------------
|
||||
|
||||
After you've clicked **Fetch registration form**, the chat client will contact
|
||||
the chat provider, ask for its registration form and then present it to you.
|
||||
|
||||
Different chat providers have different registration forms, but they're all
|
||||
relatively similar.
|
||||
|
||||
Check the security score
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
At the top of the form you'll see a colored bar containing the text **xmpp.net score**.
|
||||
This shows the security score for this server as determined by `xmpp.net <https://xmpp.net>`_
|
||||
where you can test out a server for yourself. You should generally avoid providers with
|
||||
a poor security score (colored in red).
|
||||
|
||||
Choosing a username
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
As you can see in the registration form, the **username** consists of two
|
||||
parts separated with an **@** sign, similar to an email address.
|
||||
|
||||
The first part is your unique *handle* which you need to choose. The second part
|
||||
is the domain name of the chat provider, the one which you chose in the previous step
|
||||
when you fetched the registration form.
|
||||
|
||||
When you want to give someone your XMPP chat username, or when you want to add
|
||||
someone else as a contact, you need to specify it in full, like you would an email address.
|
||||
|
||||
Once you've chosen your user name and password, click **Register**. If
|
||||
Successful, you'll be automatically logged in to your new account.
|
||||
|
||||
|br|
|
||||
|
||||
.. figure:: images/add-contact.png
|
||||
:align: left
|
||||
:alt: Adding a contact in converse.js
|
||||
|
||||
The form for adding a new contact
|
||||
|
||||
|
||||
Adding a contact
|
||||
================
|
||||
|
||||
In order to start chatting with someone, you first need to add them as a contact.
|
||||
|
||||
To do this, click the **Add a contact** link in the **Contacts** tab. This will
|
||||
slide open a dropdown in which you can type the username of the person you'd
|
||||
like to add.
|
||||
|
||||
Remember, an XMPP username (also called a JID or Jabber ID) is similar to an
|
||||
email address, in that you have both the user's *handle* and the *domain name*
|
||||
of the provider, separated with an **@** sign.
|
||||
|
||||
Once you've typed the username and clicked submit, your request will be sent to
|
||||
this person. If they are online, they will immediately be notified of your
|
||||
request, otherwise they'll see it next time they come online.
|
||||
|
||||
Technically, when you add someone as a contact, you're doing two things. Firstly,
|
||||
you are adding the contact to your *roster* (think of it as an address book) and secondly
|
||||
you are asking to be notified whenever that person comes online.
|
||||
|
||||
.. figure:: images/pending-contact.jpg
|
||||
:align: left
|
||||
:alt: A pending contact
|
||||
|
||||
A pending contact
|
||||
|
||||
A pending contact
|
||||
-----------------
|
||||
|
||||
The person you are adding as a contact has the option to either accept or decline your request.
|
||||
Until that decision has been made, they will appear in your roster as a
|
||||
so-called *pending* contact. In other words, their final status is pending on whether
|
||||
they accept or decline your request.
|
||||
|
||||
.. figure:: images/ungrouped-contact.png
|
||||
:align: right
|
||||
:alt: A normal, ungrouped contact
|
||||
|
||||
A normal contact
|
||||
|
||||
A normal contact
|
||||
----------------
|
||||
|
||||
If the person accepts your contact request, they will get a *chat status
|
||||
indicator* in your roster and will also become clickable. Clicking on the name
|
||||
of the user will open a chat box in which you can then start chatting with that
|
||||
user.
|
||||
|
||||
.. figure:: images/remove-contact.png
|
||||
:align: left
|
||||
:alt: Removing a contact
|
||||
|
||||
Removing a contact
|
||||
|
||||
Removing a contact
|
||||
==================
|
||||
|
||||
To remove a contact, hover your mouse over their name and then click on the
|
||||
trash icon. You will be prompted to confirm, and if you do, the contact will no
|
||||
longer be visible in your roster.
|
||||
|
@ -58,6 +58,9 @@
|
||||
<li class="page-scroll">
|
||||
<a href="#contact">Contact</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="/docs/html/manual.html">User Manual</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="/docs/html/index.html">Documentation</a>
|
||||
</li>
|
||||
|