annotate doc/jp/index.rst @ 2946:ce16847a7b6d

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.
author Goffi <goffi@goffi.org>
date Fri, 22 Feb 2019 18:58:59 +0100
parents
children 8ec35cf13f66
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2946
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
1 ==
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
2 jp
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
3 ==
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
4
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
5 ``jp`` is the CLI (Command Line Interface) frontend of Salut à Toi
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
6
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
7 Overview
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
8 ========
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
9
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
10 ``jp`` is a powerful tool to work with Salut à Toi/XMPP.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
11 With it you can send chat messages, share files, retrieve avatars, write blog entries, etc.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
12
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
13 Usage
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
14 =====
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
15
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
16 To get help on commands or their options, use::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
17
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
18 $ jp --help
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
19
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
20 which can be used on any command, so if you need help on ``message send`` command, just do::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
21
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
22 $ jp message send --help
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
23
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
24 With jp, you always enter commands first, then options and arguments.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
25
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
26 There are several levels of commands: first one is the main categorie (``message``,
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
27 ``blog``, ``avatar``, etc.), then there are often subcommands (e.g. ``message send``).
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
28
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
29 After the commands come the options. For instance if you want to send a message, you can
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
30 get the available options with ``--help`` as explained above::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
31
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
32 $ jp message send --help
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
33 usage: jp message send [-h] [-p PROFILE] [--pwd PASSWORD] [-c] [-l LANG] [-s]
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
34 [-n] [-S SUBJECT] [-L SUBJECT_LANG]
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
35 [-t {chat,error,groupchat,headline,normal,auto}]
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
36 [-e ALGORITHM] [--encrypt-noreplace] [-x | -r]
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
37 jid
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
38
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
39 positional arguments:
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
40 jid the destination jid
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
41
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
42 optional arguments:
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
43 -h, --help show this help message and exit
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
44 -p PROFILE, --profile PROFILE
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
45 Use PROFILE profile key (default: @DEFAULT@)
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
46 --pwd PASSWORD Password used to connect profile, if necessary
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
47 -c, --connect Connect the profile before doing anything else
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
48 -l LANG, --lang LANG language of the message
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
49 -s, --separate separate xmpp messages: send one message per line
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
50 instead of one message alone.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
51 -n, --new-line add a new line at the beginning of the input (usefull
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
52 for ascii art ;))
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
53 -S SUBJECT, --subject SUBJECT
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
54 subject of the message
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
55 -L SUBJECT_LANG, --subject_lang SUBJECT_LANG
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
56 language of subject
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
57 -t {chat,error,groupchat,headline,normal,auto}, --type {chat,error,groupchat,headline,normal,auto}
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
58 type of the message
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
59 -e ALGORITHM, --encrypt ALGORITHM
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
60 encrypt message using given algorithm
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
61 --encrypt-noreplace don't replace encryption algorithm if an other one is
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
62 already used
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
63 -x, --xhtml XHTML body
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
64
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
65 If you want to send a message to, say, ``pierre@example.net``, and encrypt it with OMEMO,
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
66 just do the following::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
67
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
68 echo "hi, I'm writing with jp" | jp message send -e omemo pierre@example.net
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
69
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
70 (note that with OMEMO, you need to have previously validated fingerprint of your contact
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
71 for this to work).
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
72
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
73 The different commands are explained in dedicated sections.
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
74
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
75 .. toctree::
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
76 :caption: jp commands:
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
77 :glob:
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
78 :maxdepth: 2
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
79
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
80 common_arguments
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
81 *
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
82
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
83
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
84 Tutorial
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
85 ========
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
86
ce16847a7b6d doc: documentation first draft:
Goffi <goffi@goffi.org>
parents:
diff changeset
87 You can check this third party tutorial: https://blog.agayon.be/sat_jp.html