erebion/libervia-backend
Watch
1
0
Fork
You've already forked libervia-backend
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc: documentation first draft:

Browse source 
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.
This commit is contained in:
Goffi 2019-02-22 18:58:59 +01:00
commit 31a16d1fab
9 changed files with 1097 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

19
doc/Makefile Normal file
View file

@ -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)

184
doc/conf.py Normal file
View file

@ -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 -------------------------------------------------

34
doc/index.rst Normal file
View file

@ -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`

188
doc/installation.rst Normal file
View file

@ -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)

286
doc/jp/blog.rst Normal file
View file

@ -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

207
doc/jp/common_arguments.rst Normal file
View file

@ -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

87
doc/jp/index.rst Normal file
View file

@ -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

57
doc/jp/message.rst Normal file
View file

@ -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

35
doc/make.bat Normal file
View file

@ -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