# HG changeset patch # User Goffi # Date 1550858339 -3600 # Node ID ce16847a7b6d120e51cf4375b574c223696950d6 # Parent 6c264c224614b33be649adab71184f2667aa8f5c 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. diff -r 6c264c224614 -r ce16847a7b6d doc/Makefile --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Makefile Fri Feb 22 18:58:59 2019 +0100 @@ -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) \ No newline at end of file diff -r 6c264c224614 -r ce16847a7b6d doc/conf.py --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/conf.py Fri Feb 22 18:58:59 2019 +0100 @@ -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 ------------------------------------------------- diff -r 6c264c224614 -r ce16847a7b6d doc/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/index.rst Fri Feb 22 18:58:59 2019 +0100 @@ -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 `_ (also available via a `web link `_) + + +.. toctree:: + :caption: Contents: + :maxdepth: 3 + + installation.rst + /jp/index.rst + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff -r 6c264c224614 -r ce16847a7b6d doc/installation.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/installation.rst Fri Feb 22 18:58:59 2019 +0100 @@ -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 `__ 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`` `__ + | ``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) diff -r 6c264c224614 -r ce16847a7b6d doc/jp/blog.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/blog.rst Fri Feb 22 18:58:59 2019 +0100 @@ -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 `_ below + +If you don't change anything or publish an empty blog post, the edition will be cancelled. + +In the metadata (see `below `_ 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 `_ 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 `_. 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 diff -r 6c264c224614 -r ce16847a7b6d doc/jp/common_arguments.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/common_arguments.rst Fri Feb 22 18:58:59 2019 +0100 @@ -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 `_). Modern pubsub services should + implement `Result Set Management `_ (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 `_, 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 `_, 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 diff -r 6c264c224614 -r ce16847a7b6d doc/jp/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/index.rst Fri Feb 22 18:58:59 2019 +0100 @@ -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 diff -r 6c264c224614 -r ce16847a7b6d doc/jp/message.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/jp/message.rst Fri Feb 22 18:58:59 2019 +0100 @@ -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 diff -r 6c264c224614 -r ce16847a7b6d doc/make.bat --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/make.bat Fri Feb 22 18:58:59 2019 +0100 @@ -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