doc: documentation first draft:

this patch starts the local documentation, existing documentation will be imported from wiki/other places to this folder and updated.
This doc is using reStructuredText format and will be generated with Sphinx.

doc/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = .build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/conf.py

@@ -0,0 +1,184 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+import os.path
+import re
+
+
+# -- Project information -----------------------------------------------------
+
+project = u'Salut à Toi'
+copyright = u'2019, Salut à Toi'
+author = u'Salut à Toi team'
+
+doc_dir = os.path.dirname(os.path.abspath(__file__))
+version_path = os.path.join(doc_dir, '../sat/VERSION')
+with open(version_path) as f:
+    version_full = f.read()
+
+# The short X.Y version
+version = re.match(r'[0-9.]+', version_full).group()
+
+# The full version, including alpha/beta/rc tags
+release = version_full
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [u'.build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['.static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'SalutToidoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'SalutToi.tex', u'Salut à Toi Documentation',
+     u'Salut à Toi team', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'saluttoi', u'Salut à Toi Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'SalutToi', u'Salut à Toi Documentation',
+     author, 'SalutToi', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']
+
+
+# -- Extension configuration -------------------------------------------------

doc/index.rst

@@ -0,0 +1,34 @@
+=========================
+Salut à Toi documentation
+=========================
+
+Welcome to Salut à Toi's documentation. You'll find here both end-user and developer documentations.
+
+Salut à Toi (or SàT) is a Libre communication ecosystem based on XMPP standard. It allows you to do many things such as:
+
+- instant messaging
+- (micro)blogging
+- file sharing
+- managing photo albums
+- organizing/managing events
+- handling tasks
+- etc.
+
+It features many interfaces (desktop, mobile, web, command line, console), and is multi-platforms.
+
+You can follow this documentation to learn more on it, or join our official XMPP room at `sat@chat.jabberfr.org <xmpp:sat@chat.jabberfr.org?join>`_ (also available via a `web link <https://chat.jabberfr.org/converse.js/sat@chat.jabberfr.org>`_)
+
+
+.. toctree::
+   :caption: Contents:
+   :maxdepth: 3
+
+   installation.rst
+   /jp/index.rst
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

doc/installation.rst

@@ -0,0 +1,188 @@
+============
+Installation
+============
+
+This are the instructions to install SàT using Python.
+Note that if you are using GNU/Linux, Salut à Toi may already be present on your distribution.
+
+Salut à Toi is made of one backend, and several frontends. To use it, the first thing to do is to install the backend.
+
+We recommand to use development version for now, until the release of
+0.7 version which will be "general public" version.
+
+Also note that SàT is still using Python 2 (this will change for 0.8 version which will be Python 3 only), so all instructions below have to be made using python 2.
+
+Development version
+-------------------
+
+*Note for Arch users: a pkgbuild is available for your distribution on
+AUR, check sat-xmpp-hg (as well as other sat-\* packages).*
+
+You can install the latest development version using pip. You need to
+have the following dependencies installed first:
+
+-  Python 2 with development headers
+-  Mercurial
+-  VirtualEnv
+-  libcairo 2 with development headers
+-  libjpeg with development headers
+-  libgirepository 1.0 with development headers
+-  libdbus-1 with development headers
+-  libdbus-glib-1 with development headers
+-  libxml2 with development headers
+-  libxlt2 with development headers
+-  D-Bus x11 tools (this doesn't needs X11, it is just needed for dbus-launch)
+-  cmake
+
+On Debian and derivatives, you can get all this with following command::
+
+  $ sudo apt-get install python-dev mercurial virtualenv libxml2-dev libxslt-dev libcairo2-dev libjpeg-dev libgirepository1.0-dev libdbus-1-dev libdbus-glib-1-dev dbus-x11 cmake
+
+Now go in a location where you can install Salut à Toi, for
+instance your home directory::
+
+  $ cd
+
+And enter the following commands (note that *virtualenv2* may be named
+*virtualenv* on some distributions, just be sure it's Python **2** version)::
+
+  $ virtualenv2 env
+  $ source env/bin/activate
+  $ pip install hg+https://repos.goffi.org/sat
+
+Don't worry if you see the following message, SàT should work anyway::
+
+  Failed building wheel for pygobject
+
+After installing SàT, you need to install the media::
+
+  $ cd
+  $ hg clone https://repos.goffi.org/sat_media
+
+then, create the file ~/.config/sat/sat.conf containing:
+
+.. sourcecode:: cfg
+
+  [DEFAULT]
+  media_dir = ~/sat_media
+
+Of course, replace ``~/sat_media`` with the actual path you have used.
+
+.. following part is currently hidden until v0.7 is released
+
+  Last release
+  ------------
+
+  This release is really old and code has changed a lot since it.
+  Furthermore, stable version is currently not maintained. We recommend to use current dev version until version 0.7 is released.
+
+  If you are willing to install last release anyway, here are the instructions.
+
+  You can automatically install SàT and its dependencies using
+  easy_install or pip. You will however need to install Python's headers
+  (needed to build some packages),
+  `PyGObject <http://ftp.gnome.org/pub/GNOME/sources/pygobject/>`__ and
+  developments version of libxml2 and libxslt (to compile lxml python
+  library). On some ARM systems like Raspberry Pi or OLinuXino, it is also
+  required to install libjpeg-dev and libffi-dev beforehand.
+
+  The environment variable SAT_INSTALL customises the installation, it
+  contains flags separated by spaces:
+
+  -  "nopreinstall" skip all preinstallation checks
+  -  "autodeb" automatically install missing packages on Debian based
+     distributions
+
+  PyGobject is automatically installed on Debian based distributions if
+  "autodeb" option is set. Indeed, on Debian based distribution, you can
+  type:
+
+  | ``sudo apt-get install python-pip python-virtualenv python-dev libxml2-dev libxslt-dev libjpeg-dev libffi-dev zlib1g-dev``
+  | ``virtualenv --system-site-packages sat``
+  | ``source sat/bin/activate``
+  | ``pip2 install -U setuptools``
+  | ``SAT_INSTALL="autodeb" pip2 install sat``
+
+  After installing SàT, you need to install the media:
+
+  | ``mkdir -p /path/to/sat_media``
+  | ``cd /path/to/sat_media``
+  | ``wget ``\ ```ftp://ftp.goffi.org/sat_media/sat_media.tar.bz2`` <ftp://ftp.goffi.org/sat_media/sat_media.tar.bz2>`__
+  | ``tar -jxvf sat_media.tar.bz2``
+
+  then, create a ~/.sat.conf file which contains:
+
+  | ``[DEFAULT]``
+  | ``media_dir=/path/to/sat_media``
+
+  Of course, replace /path/to/sat_media with the actual path you want to
+  use.
+
+Usage
+=====
+
+To launch the sat backend, enter::
+
+  $ sat
+
+…or, if you want to launch it in foreground::
+
+  $ sat fg
+
+You can stop it with::
+
+  $ sat stop
+
+To know if backend is launched or not::
+
+  $ sat status
+
+**NOTE**: since SàT v0.5.0, the backend is automatically launched when a frontend needs it.
+
+You can check that SàT is installed correctly by trying jp (the backend need to be launched first, check below)::
+
+  $ jp --version
+  jp 0.7.0D « La Commune » (rev 2dd53ffa4781 (default 2019-02-22 18:58 +0100) +110) Copyright (C) 2009-2019 Jérôme Poisson, Adrien Cossa
+  This program comes with ABSOLUTELY NO WARRANTY;
+  This is free software, and you are welcome to redistribute it under certain conditions.
+
+If you have a similar output, SàT is working.
+
+Frontends
+=========
+
+So far, the following frontends exist and are actively maintained:
+
+Cagou
+  desktop/mobile (Android) frontend
+
+Libervia
+  the web frontend
+
+Primitivus
+  Text User Interface
+
+jp
+  Command Line Interface
+
+To launch Primitivus, just type::
+
+  $ primitivus
+
+then create a profile (XMPP account must already exist).
+
+To use jp, follow its help::
+
+  $ jp --help
+
+
+There are some other frontends:
+
+Bellaciao
+  based on Qt, a rich desktop frontend (currently on hold)
+
+Wix
+  former desktop frontend based on WxWidgets (deprecated with version 0.6.0)
+
+Sententia
+  Emacs frontend developed by a third party (development is currently stalled)

doc/jp/blog.rst

@@ -0,0 +1,286 @@
+.. highlight:: sh
+
+================================
+blog: (micro)blogging management
+================================
+
+Blog commands are high level tools to handle an XMPP blog.
+They are using the generic pubsub arguments
+
+set
+===
+
+publish a blog item.
+
+:ref:`pubsub_common` commands are used to specify the destination item.
+
+``stdin`` is used to get the body of the blog post.
+
+examples
+--------
+
+Create a blog post with a body, a subject, 2 tags, and with comments allowed::
+
+  $ echo "This is post body" | jp blog set -T "This is a test message" -t test -t jp -C
+
+Create a blog post with rich content using `markdown` syntax, and no subject::
+
+  $ echo "This is a **rich** body" | jp blog set -S markdown
+
+get
+===
+
+get command retrieves one or move blog post from specified location (by default the
+personal blog of the profile).
+
+output can be customised to only retrieve some keys, or to use a specific template.
+
+:ref:`pubsub_common` commands are used to specify the blog location.
+
+examples
+--------
+
+Retrieve personal blog of the profile using `fancy` output with a verbosity of 1 (to show
+publication date)::
+
+  $ jp blog get -O fancy -v
+
+Retrieve *title* and *publication date* of last 3 blog posts from the blog at
+https://www.goffi.org::
+
+  $ jp blog get -m 3 -u https://www.goffi.org -k title -k published
+
+Retrieve last 2 posts of personal blog, and output them in browser using default
+template::
+
+  $ jp blog get -m 2 -O template --oo browser
+
+edit
+====
+
+With edit command you can create a new blog post or modify an existing one using your
+local editor (the one set in ``$EDITOR``). You'll edit 2 things: the body of the post, and
+the metadata which contain things like title, comments infos, or tags.
+
+For some common editors (like **vim** or **Emacs**), the editor will be automatially
+opened using a split screen with *body* in one side, and metadata on the other. If the
+editor is not supported or doesn't support split screen, you'll edit first the *body*, then
+the *metadata*. You can also specify editor and arguments in ``sat.conf``, see
+`configuration <edit_conf_>`_ below
+
+If you don't change anything or publish an empty blog post, the edition will be cancelled.
+
+In the metadata (see `below <edit_metadata_>`_ for details), you can use
+``"publish": false`` to forbid the publication. In this case, when you'll save
+your modification and quit your editor, the blog post will not be published but
+saved locally in a draft. To continue your work later, just start your edition with the
+``-D, --current`` option like this::
+
+  $ jp blog edit -D
+
+Note that item location must be re-specified if it has been used to create the draft, so
+you'll have to reproduce the arguments to specify service, node or item (or the URL),
+other data like tags will be restored from draft file of metadata.
+
+You can specify the syntax by using ``-S SYNTAX, --syntax SYNTAX``. If not specified, the
+syntax set in your parameters will be used.
+
+When you edit a blog post, it is often useful to activate the ``-P, --preview`` option,
+this will launch a web browser and refresh the page each time you save a modification in
+your editor. By default, the browser registered as default in your system will be used,
+and a new tab will be opened on each modification. This is not ideal, and we recommand to
+set you configuration to activate automatic refreshing of the page instead, see `preview
+configuration <edit_preview_>`_ below to see how to do.
+
+examples
+--------
+
+Edit a new blog post with comments on your personal blog, using default syntax and preview::
+
+  $ jp blog edit -P --comments
+
+Modifiy a draft previously saved using the ``"publish": false`` metadata::
+
+  $ jp blog edit -D
+
+Correct a typo in your last published blog post::
+
+  $ jp blog edit --last-item
+
+Edit the blog item at an HTTPS URL using XHTML syntax::
+
+  $ jp blog edit -u https://www.example.net/some_xmpp_blog_article.html -S xhtml
+
+Create a new blog post on a XMPP blog node using its HTTPS URL (supposing here that
+https://example.net is a XMPP blog node)::
+
+  $ jp blog edit -u https://www.example.net
+
+.. _edit_metadata:
+
+metadata
+--------
+
+Metadata is set using a JSON object. The key you can use are:
+
+publish
+  boolean indicating if item can be published. Set to ``false`` if you want to work on a
+  draft and to avoid accidental publication.
+
+atom_id
+  atom entry identifier. This should not be modified manually.
+
+published
+  time of initial publication (unix time). This should not be modified manually.
+
+language
+  language of the content
+
+comments
+  array of URIs to the comments node, if any.
+
+tag
+  array of tags, if any
+
+author
+  human readable name of the entry author
+
+author_jid
+  jid of the author. This should notbe modified manually.
+
+author_jid_verified
+  true if the pubsub service confirmed that author_jid is the one of the publisher. It is
+  useless to modify this variable.
+
+title
+  the title of the message
+
+title_rich
+  the rich title of the message, in current text syntax. It will be automatically
+  converted to xhtml.
+
+.. _edit_conf:
+
+configuration
+-------------
+
+editor
+^^^^^^
+
+Local editor used is by default the one set in ``$EDITOR`` environment variable, but you
+can specify one in ``sat.conf``. To do so, you have to set the name of an editor
+executable in  the ``editor`` option in ``[jp]`` section.
+
+You can specify the args to use by using ``blog_editor_args`` option. Use
+``{content_file}`` to get the path of the main content file (the body of the blog post),
+and ``{metadata_file}`` to get the path of the json metadata.
+
+.. sourcecode:: cfg
+
+   [jp]
+   editor = kate
+   blog_editor_args = {content_file} {metadata_file}
+
+.. _edit_preview:
+
+preview
+^^^^^^^
+
+To set the preview, you can use the options ``blog_preview_open_cmd`` and
+``blog_preview_update_cmd`` in your ``[jp]`` section. the former is the command to use to
+open your browser when edition starts, and the later is the command to use when a
+modification is saved. In both cases you may use ``{url}`` to set the location of local HTML file.
+
+This can be use to activate automatic refreshing of the page.
+
+For **Konqueror**, you can use its D-Bus API to do refreshing. Ensure that ``qdbus`` is
+installed on your system, and enter the following lines in your ``sat.conf``:
+
+.. sourcecode:: cfg
+
+    [jp]
+    blog_preview_open_cmd = konqueror {url}
+    blog_preview_update_cmd = /bin/sh -c "qdbus $(qdbus org.kde.konqueror\*) /konqueror/MainWindow_1 reload"
+
+For **Firefox**, you may use ``xdotool`` on X11. Once you have installed this tool, enter the
+following lines in your ``sat.conf``:
+
+.. sourcecode:: cfg
+
+    [jp]
+    blog_preview_open_cmd = firefox -new-tab {url}
+    blog_preview_update_cmd = /bin/sh -c "WID=$(xdotool search --name 'Mozilla Firefox' | head -1); xdotool windowactivate $WID; xdotool key F5"
+
+This *xdotool* technique can be adapted to other browsers.
+
+syntax extensions
+^^^^^^^^^^^^^^^^^^
+
+A dictionary with a mapping from syntax name to file extension can be used. This can be
+useful to activate the right syntax highlighting in your editor. There is a default
+mapping which can be overriden.
+
+The mapping is set in the ``syntax_ext_dict`` option of the ``[jp]`` section of your
+``sat.conf`` file. For instance, if your prefer do your ``.markdown`` for temp files
+instead of the default ``.md``, you can use this:
+
+.. sourcecode:: cfg
+
+   [jp]
+   syntax_ext_dict = {"markdown": "markdown"}
+
+the first ``markdown`` is the name of the syntax (could an other syntax like ``xhtml``),
+while the second if the file extension.
+
+preview
+=======
+
+This command will show the specified file in browser, and refresh it when changes are
+detected. Configuration is the same as for `edit preview <edit_preview_>`_. This is can be
+used if you have already started an edition with ``jp blog edit`` but forgot to use the ``-P, --preview`` arguments.
+
+example:
+--------
+
+Preview the draft at ``~/local/sat/blog/some_name/blog_something.md``::
+
+  $ jp blog preview ~/local/sat/blog/some_name/blog_something.md
+
+import
+======
+
+With this command you can import an external blog in a XMPP blog at the specified pubsub
+location.
+
+The import is done using an *importer* name and a *location* which depends of the importer
+(it can be a path to a file, an URL to a blog, or something else). Use empty nothing to
+get list of importers, and specify only importer name to get its description.
+
+By default, found images are re-uploaded to XMPP server, if you want to keep original
+URLs, use the ``--no-images-upload`` option.
+
+Alternatively, you can re-upload images except for a specific host with ``--upload-ignore-host UPLOAD_IGNORE_HOST``. The images for the specified host will keep there original URLs while other will be uploaded to XMPP server.
+
+You shoud specify original blog host using ``--host HOST`` argument, this is used notably
+to reconstruct relative URLs of media.
+
+Importers may have specific options, you can set them using the ``-o NAME VALUE, --option NAME VALUE`` argument. Check the importer description for details.
+
+examples:
+---------
+
+List available importers::
+
+  $ jp blog import
+
+Get description of ``dotclear`` importer::
+
+  $ jp blog import dotclear
+
+Import a Dotclear blog::
+
+  $ jp blog import dotclear /path/to/dotclear.dump
+
+Import a Dotclear blog without uploading images::
+
+  $ jp blog import --no-images-upload dotclear /path/to/dotclear.dump

doc/jp/common_arguments.rst

@@ -0,0 +1,207 @@
+================
+common arguments
+================
+
+Some arguments are used in many commands. This page describe them.
+
+profile
+=======
+
+profile arguments are really common, they allow you to select your profile.
+If you don't select any, the default profile is used, which is the first
+profile created or the one you have explicitly set. You can check which profile
+is used by default with ``jp profile default``.
+
+The common arguments for profile are:
+
+``-p PROFILE, --profile PROFILE``
+  to select the name of your profile. It can be a profile key like ``@DEFAULT@``
+
+``-c, --connect``
+  connect the profile to the XMPP server before doing anything else. If your
+  profile is already connected, nothing happen. This is specially useful in scripts.
+
+``--start-session``
+  starts a session without connecting, this can be needed if you can't connect but
+  you need to access your session e.g. to change parameters.
+  This is advanced used and is not need in most common cases.
+
+``--pwd PASSWORD``
+  the password of your profile, needed if the session is not started yet.
+
+.. note::
+
+   jp does not yet prompt for password when needed, this mean that using the ``--pwd``
+   option is not secure if you are not the only user of your machine: the password will
+   appear **IN CLEAR** in the list of launched process, or in the history of your shell.
+   If you are on a shared machine or if anybody can access your shell history at some
+   point, you should connect first your profile with an other frontend (Primitivus for
+   instance).  This will be fixed in a future version of jp.
+
+.. _pubsub_common:
+
+pubsub
+======
+
+pubsub arguments are used in many commands, they allow you to select a service, node and
+items. Depending on the command, you may only not be able to select an item, or you may
+select one or multiple items.
+
+The common arguments for pubsub are:
+
+``-u PUBSUB_URL, --pubsub-url PUBSUB_URL``
+  retrieve pubsub information from an URL. You can use either and ``xmpp:`` scheme or an
+  ``https:`` (or ``http:``) scheme. In the later case, the HTML page will be downloaded to
+  retrieve the location of the XMPP node/item, if available.
+  Note that you can override parts of the location in the URL if you specify service, node
+  or item.
+
+  e.g.::
+
+    $ jp blog get -u https://www.goffi.org
+
+``-s SERVICE, --service``
+  used to specifiy the JID of the pubsub service
+
+``-n NODE, --node NODE``
+  used to specifiy the pubsub node
+
+``-i ITEM, --item ITEM``
+  for commands where an item can be specified, you do it with this option. In some
+  commands, multiple items can be specified, in this case just use this arguments several
+  times.
+
+``-L, --last-item``
+  when an item id is needed, you can use this option to retrieve the last published item.
+  e.g.::
+
+    $ jp blog edit --last-item
+
+``-M, --max-items``
+  use to specify a maxium number of items to retrieve, when it makes sense.
+  Note that this is using the pubsub max (i.e. defined in
+  `XEP-0060 <https://xmpp.org/extensions/xep-0060.html>`_). Modern pubsub services should
+  implement `Result Set Management <https://xmpp.org/extensions/xep-0059.html>`_ (RSM) and in
+  this case the ``-m, --max`` argument should be prefered. See below for RSM common
+  arguments.
+
+result set management
+=====================
+
+Result Set Management (RSM) common arguments are used to navigate into pages of results
+when lot of elements may be expected. Given a result with a large number of arguments, a
+*page* is set of elements which correspond to an *index* (a page number). For instance if
+you have 123 elements, you can ask them 10 by 10, and *index 1* match elements from 11 to
+20 included.
+
+
+``-a ITEM_ID, --after ITEM_ID``
+  find page after this item. You usually use the last item id of the latest page you got.
+
+``-b ITEM_ID, --before ITEM_ID``
+  find page before this item. This this usually used when you check items backwards
+
+``--index RSM_INDEX``
+  index of the page to retrieve. Note that first page has index **0**.
+
+``-m RSM_MAX, --max RSM_MAX``
+  used to specify a maxium number of items to retrieve per page. Note that the actual
+  maximum number of items per page used may be lower if the service used consider that
+  your request is too big.
+
+message archive management
+==========================
+
+Message Archive Management (MAM) argument is used by some commands (related to instant message or
+pubsub) to filter results.
+
+There is currently only one argument in this group:
+
+``-f FILTER_NAME VALUE, --filter FILTER_NAME VALUE``
+  specify a MAM filter to use. Depending on the service supporting MAM, some filters can
+  be used to do things like full text search. The available filters depend on the service
+  you use, please check documentation of your service.
+
+order-by
+========
+
+Order-By argument specify or the returned elements are sorted.
+
+There is currently only one argument in this group:
+
+``-o {creation,modification}, --order-by {creation,modification}``
+  specify how result is sorted. with ``creation``, first created element is returned
+  first. There is no notion of *creation* of *modification* in original
+  `pubsub XEP <https://xmpp.org/extensions/xep-0060.html>`_, as publishing an item with an
+  existing id will overwrite the older one, creating a new item. With this option, we use
+  the terms defined in `XEP-0413 <https://xmpp.org/extensions/xep-0413.html>`_, and
+  *creation* time is the time when the first item has been published, before being
+  overwritten.
+
+  In the case of ``modification``, if an item is overwritten, it reappears on top, this is
+  the default pubsub sorting order.
+
+progress
+========
+
+This single option may be used when a long operation is happening, like a file transfer.
+
+``-P, --progress``
+  Show progress bar.
+
+verbose
+=======
+
+``--verbose, -v``
+  Add a verbosity level (can be used multiple times). Use to have more concise output by
+  default when it makes sense.
+
+draft
+=====
+
+Common arguments used when an edition is potentially long to do, and a file may be kept
+until publication.
+
+
+``-D, --current``
+  Used when you have started to edit something (e.g. a blog post), which is not yet
+  published, and you want to continue your work.
+
+  e.g.::
+
+    $ jp blog edit -D
+
+``-F DRAFT_PATH, --draft-path DRAFT_PATH``
+  Used when you have started to edit something and want to continue your work from this
+  file. In other words, it's similar to ``-D, --current`` except that you specify the file
+  to use instead of using the last available draft.
+
+output
+======
+
+Output is used when you want to get the result of the command in a specific way. It may be
+used, for instance, to retrieve the result formatted in JSON so the data can be easily
+manipulated by a script, or if you want only a specific element of the result.
+
+``-O {…}, --output {…}``
+  specifiy the output to use. Available options depends of the command you are using,
+  check ``jp [your command] --help`` to know them.
+
+  e.g.::
+
+    $ jp blog get -O json
+
+``--output-option OUTPUT_OPTS, --oo OUTPUT_OPTS``
+  depending of the output selected, you may have options to customise the output.
+  For instance, if you use the ``template`` output, you may use an option to display the
+  result in a browser.
+
+  e.g.::
+
+    $ jp blog
+
+  Some options expect parameters, in this case they can be specified using ``=``.
+
+  e.g. specifiying a template to use::
+
+    $ jp blog get -O template --oo browser --oo template=/tmp/my_template.html

doc/jp/index.rst

@@ -0,0 +1,87 @@
+==
+jp
+==
+
+``jp`` is the CLI (Command Line Interface) frontend of Salut à Toi
+
+Overview
+========
+
+``jp`` is a powerful tool to work with Salut à Toi/XMPP.
+With it you can send chat messages, share files, retrieve avatars, write blog entries, etc.
+
+Usage
+=====
+
+To get help on commands or their options, use::
+
+   $ jp --help
+
+which can be used on any command, so if you need help on ``message send`` command, just do::
+
+   $ jp message send --help
+
+With jp, you always enter commands first, then options and arguments.
+
+There are several levels of commands: first one is the main categorie (``message``,
+``blog``, ``avatar``, etc.), then there are often subcommands (e.g. ``message send``).
+
+After the commands come the options. For instance if you want to send a message, you can
+get the available options with ``--help`` as explained above::
+
+   $ jp message send --help
+   usage: jp message send [-h] [-p PROFILE] [--pwd PASSWORD] [-c] [-l LANG] [-s]
+                          [-n] [-S SUBJECT] [-L SUBJECT_LANG]
+                          [-t {chat,error,groupchat,headline,normal,auto}]
+                          [-e ALGORITHM] [--encrypt-noreplace] [-x | -r]
+                          jid
+
+   positional arguments:
+     jid                   the destination jid
+
+   optional arguments:
+     -h, --help            show this help message and exit
+     -p PROFILE, --profile PROFILE
+                           Use PROFILE profile key (default: @DEFAULT@)
+     --pwd PASSWORD        Password used to connect profile, if necessary
+     -c, --connect         Connect the profile before doing anything else
+     -l LANG, --lang LANG  language of the message
+     -s, --separate        separate xmpp messages: send one message per line
+                           instead of one message alone.
+     -n, --new-line        add a new line at the beginning of the input (usefull
+                           for ascii art ;))
+     -S SUBJECT, --subject SUBJECT
+                           subject of the message
+     -L SUBJECT_LANG, --subject_lang SUBJECT_LANG
+                           language of subject
+     -t {chat,error,groupchat,headline,normal,auto}, --type {chat,error,groupchat,headline,normal,auto}
+                           type of the message
+     -e ALGORITHM, --encrypt ALGORITHM
+                           encrypt message using given algorithm
+     --encrypt-noreplace   don't replace encryption algorithm if an other one is
+                           already used
+     -x, --xhtml           XHTML body
+
+If you want to send a message to, say, ``pierre@example.net``, and encrypt it with OMEMO,
+just do the following::
+
+   echo "hi, I'm writing with jp" | jp message send -e omemo pierre@example.net
+
+(note that with OMEMO, you need to have previously validated fingerprint of your contact
+for this to work).
+
+The different commands are explained in dedicated sections.
+
+.. toctree::
+   :caption: jp commands:
+   :glob:
+   :maxdepth: 2
+
+   common_arguments
+   *
+
+
+Tutorial
+========
+
+You can check this third party tutorial: https://blog.agayon.be/sat_jp.html

doc/jp/message.rst

@@ -0,0 +1,57 @@
+.. highlight:: sh
+
+================================
+message: chat message management
+================================
+
+Message commands let you send chat messages or manage your server message archives.
+
+send
+====
+
+send a message to a contact or a chat room.
+``stdin`` is used as message source.
+You can encrypt your message using ``--encrypt [ALGORITHM]`` argument, this will create an encrypted session and replace existing one if needed.
+You can manage your encrypted session using ``encryption`` command.
+
+examples
+--------
+
+Send a message to a contact::
+
+  $ echo 'Salut à Toi!' | jp message send louise@example.net
+
+Send a message encrypted with OMEMO::
+
+  $ echo 'pssst, this message is encrypted' | jp message send -o omemo louise@example.net
+
+.. note::
+
+  Fingerprints of your destinee must have been accepted before using OMEMO, else message can't be encrypted
+
+Send a ``normal`` message marked as French with a subject::
+
+  $ echo 'Bonjour, je vous écris avec « Salut à Toi »' | jp message send -l fr -t normal -S 'Ceci est un message de test'
+
+mam
+===
+
+query archives using MAM.
+This command allows you to check message archive kept on the server (i.e. not the local copy).
+You usually want to specify a starting point, and a number of message to retrieve. If too many messages
+are available, you'll have to use RSM commands to navigate through the results.
+
+examples
+--------
+
+Retrieve messages from last 2 days::
+
+  $ jp message mam -S "2 days ago"
+
+Retrieve messages from last 5 hours on SàT official chat room::
+
+  $ jp message mam -S "2 hours ago" -s sat@chat.jabberfr.org
+
+Retrieve 2 first messages of 2019 on SàT official chat room::
+
+  $ jp message mam -S 2019-01-01 -s sat@chat.jabberfr.org -m 2

doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=.build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd