From bd8d38d711e15d42ac8e797723af5242e4c3f4fb Mon Sep 17 00:00:00 2001 From: mathieui Date: Mon, 8 Apr 2013 18:52:35 +0200 Subject: Beginning of the migration to reST documentation --- doc/Makefile | 153 ++++++++ doc/en/configure.txt | 671 --------------------------------- doc/en/dev/contributing.txt | 71 ---- doc/en/dev/index.txt | 8 - doc/en/dev/overview.txt | 106 ------ doc/en/index.txt | 21 -- doc/en/install.txt | 118 ------ doc/en/keys.txt | 424 --------------------- doc/en/misc/correct.txt | 21 -- doc/en/misc/index.txt | 9 - doc/en/misc/separate.txt | 20 - doc/en/plugins.txt | 388 ------------------- doc/en/plugins/.translate.txt | 51 --- doc/en/plugins/admin.txt | 34 -- doc/en/plugins/alias.txt | 77 ---- doc/en/plugins/amsg.txt | 24 -- doc/en/plugins/day_change.txt | 15 - doc/en/plugins/display_corrections.txt | 32 -- doc/en/plugins/exec.txt | 38 -- doc/en/plugins/figlet.txt | 24 -- doc/en/plugins/gpg.txt | 101 ----- doc/en/plugins/index.txt | 155 -------- doc/en/plugins/link.txt | 71 ---- doc/en/plugins/mpd_client.txt | 55 --- doc/en/plugins/otr.txt | 113 ------ doc/en/plugins/pacokick.txt | 27 -- doc/en/plugins/ping.txt | 26 -- doc/en/plugins/quote.txt | 35 -- doc/en/plugins/rainbow.txt | 22 -- doc/en/plugins/reminder.txt | 76 ---- doc/en/plugins/replace.txt | 71 ---- doc/en/plugins/screen_detach.txt | 15 - doc/en/plugins/send_delayed.txt | 34 -- doc/en/plugins/simple_notify.txt | 47 --- doc/en/plugins/status.txt | 25 -- doc/en/plugins/tell.txt | 40 -- doc/en/plugins/time_marker.txt | 31 -- doc/en/plugins/uptime.txt | 35 -- doc/en/ssl.txt | 62 --- doc/en/themes.txt | 96 ----- doc/en/usage.txt | 475 ----------------------- doc/en/xep.txt | 31 -- doc/images/conversation.png | Bin 9649 -> 0 bytes doc/images/correct.png | Bin 632 -> 0 bytes doc/images/data_forms.png | Bin 6522 -> 0 bytes doc/images/layers.png | Bin 15642 -> 0 bytes doc/images/list.png | Bin 5795 -> 0 bytes doc/images/muc.png | Bin 17818 -> 0 bytes doc/images/private.png | Bin 6645 -> 0 bytes doc/images/roster.png | Bin 11280 -> 0 bytes doc/images/simple_notify_example.png | Bin 5536 -> 0 bytes doc/images/ssl_warning.png | Bin 881 -> 0 bytes doc/images/tab_bar.png | Bin 712 -> 0 bytes doc/images/theme_256_colors.png | Bin 37316 -> 0 bytes doc/images/vert_tabs.png | Bin 2890 -> 0 bytes doc/poezio.txt | 83 ---- doc/source/conf.py | 249 ++++++++++++ doc/source/dev/common.rst | 8 + doc/source/dev/events.rst | 142 +++++++ doc/source/dev/index.rst | 19 + doc/source/dev/plugin.rst | 41 ++ doc/source/dev/sleek.rst | 16 + doc/source/dev/timed_events.rst | 17 + doc/source/index.rst | 35 ++ doc/source/install.rst | 129 +++++++ doc/source/themes.rst | 108 ++++++ doc/stub/args.py | 34 ++ doc/stub/config.py | 224 +++++++++++ 68 files changed, 1175 insertions(+), 3878 deletions(-) create mode 100644 doc/Makefile delete mode 100644 doc/en/configure.txt delete mode 100644 doc/en/dev/contributing.txt delete mode 100644 doc/en/dev/index.txt delete mode 100644 doc/en/dev/overview.txt delete mode 100644 doc/en/index.txt delete mode 100644 doc/en/install.txt delete mode 100644 doc/en/keys.txt delete mode 100644 doc/en/misc/correct.txt delete mode 100644 doc/en/misc/index.txt delete mode 100644 doc/en/misc/separate.txt delete mode 100644 doc/en/plugins.txt delete mode 100644 doc/en/plugins/.translate.txt delete mode 100644 doc/en/plugins/admin.txt delete mode 100644 doc/en/plugins/alias.txt delete mode 100644 doc/en/plugins/amsg.txt delete mode 100644 doc/en/plugins/day_change.txt delete mode 100644 doc/en/plugins/display_corrections.txt delete mode 100644 doc/en/plugins/exec.txt delete mode 100644 doc/en/plugins/figlet.txt delete mode 100644 doc/en/plugins/gpg.txt delete mode 100644 doc/en/plugins/index.txt delete mode 100644 doc/en/plugins/link.txt delete mode 100644 doc/en/plugins/mpd_client.txt delete mode 100644 doc/en/plugins/otr.txt delete mode 100644 doc/en/plugins/pacokick.txt delete mode 100644 doc/en/plugins/ping.txt delete mode 100644 doc/en/plugins/quote.txt delete mode 100644 doc/en/plugins/rainbow.txt delete mode 100644 doc/en/plugins/reminder.txt delete mode 100644 doc/en/plugins/replace.txt delete mode 100644 doc/en/plugins/screen_detach.txt delete mode 100644 doc/en/plugins/send_delayed.txt delete mode 100644 doc/en/plugins/simple_notify.txt delete mode 100644 doc/en/plugins/status.txt delete mode 100644 doc/en/plugins/tell.txt delete mode 100644 doc/en/plugins/time_marker.txt delete mode 100644 doc/en/plugins/uptime.txt delete mode 100644 doc/en/ssl.txt delete mode 100644 doc/en/themes.txt delete mode 100644 doc/en/usage.txt delete mode 100644 doc/en/xep.txt delete mode 100644 doc/images/conversation.png delete mode 100644 doc/images/correct.png delete mode 100644 doc/images/data_forms.png delete mode 100644 doc/images/layers.png delete mode 100644 doc/images/list.png delete mode 100644 doc/images/muc.png delete mode 100644 doc/images/private.png delete mode 100644 doc/images/roster.png delete mode 100644 doc/images/simple_notify_example.png delete mode 100644 doc/images/ssl_warning.png delete mode 100644 doc/images/tab_bar.png delete mode 100644 doc/images/theme_256_colors.png delete mode 100644 doc/images/vert_tabs.png delete mode 100644 doc/poezio.txt create mode 100644 doc/source/conf.py create mode 100644 doc/source/dev/common.rst create mode 100644 doc/source/dev/events.rst create mode 100644 doc/source/dev/index.rst create mode 100644 doc/source/dev/plugin.rst create mode 100644 doc/source/dev/sleek.rst create mode 100644 doc/source/dev/timed_events.rst create mode 100644 doc/source/index.rst create mode 100644 doc/source/install.rst create mode 100644 doc/source/themes.rst create mode 100644 doc/stub/args.py create mode 100644 doc/stub/config.py (limited to 'doc') diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..d1127133 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PoezioPlugindevelopment.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PoezioPlugindevelopment.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/PoezioPlugindevelopment" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PoezioPlugindevelopment" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/en/configure.txt b/doc/en/configure.txt deleted file mode 100644 index def86e7f..00000000 --- a/doc/en/configure.txt +++ /dev/null @@ -1,671 +0,0 @@ -Configure -========= - -The configuration is located in the file *~/.config/poezio/poezio.cfg* -On its first startup, poezio will create that file (and its containing -directories) with the default configuration. You can edit that file manually -or use the */set* command to edit some of its values directly from poezio. -This file is also used to configure key bindings, but this is explained -in the link:keys.html[Keys] documentation file. - -That file is read at each startup and the configuration is saved when poezio -is closed. - -This configuration file *requires* all global options to be in a section -named [Poezio]. Some other options can be in optional sections and will -apply only to tabs having the option’s name. - -An option is formatted with the form -====================== -option = value -====================== - -An empty value *doesn’t* mean that the default value will be used. That’s -just an empty value. To use the default value, just comment or remove the -option entirely. - -Here is a list of all the available configuration options, their meaning -and their default value. - -Configuration options ---------------------- - -Global section options -~~~~~~~~~~~~~~~~~~~~~~ - -These options have a sense when they are in the global section. Some of -them can also be in an optional configuration section, see the next -section of this documentation. - -[horizontal] - -*add_space_after_completion*:: true - - Whether or not to add a space after a completion in the middle of the - input (not at the start of it) - -*after_completion*:: , - - What will be put after the name, when using autocompletion at the - beginning of the input. A space will always be added after that - -*alternative_nickname*:: [empty] - - If you want poezio to join the room with an alternative nickname when - your nickname is already in use in the room you wanted to join, put - a non-empty value. If you don’t, poezio won't join the room - This value will be added to your nickname to create the alternative nickname. - For example, if you set "\_", and wanted to use the nickname "john", - your alternative nickname will be "john_". - -*autorejoin*:: false - - Set to true if you want to automatically rejoin the room when you're kicked. - -*autorejoin_delay*:: 5 - - Set to the number of seconds before reconnecting after getting kicked. - 0, a negative value, or no value means you reconnect instantly. - This option only works if autorejoin is enabled. - -*auto_reconnect*:: false - - Auto-reconnects you when you get disconnected. Should not be necessary, so - the default is false. - -*beep_on*:: highlight private - - The terminal can beep on various event. Put the event you want in a list - (separated by spaces). - The events can be - - highlight (when you are highlighted in a MUC) - - private (when a new private message is received, from your contacts or - someone from a MUC) - - message (any message from a MUC) - -*ca_cert_path*:: [empty] - - Path to the certificate of the Certification Authority. - As some services may keep different certificates, it is an alternative to - the Trust On First Use model provided by the “certificate” option. - This option is not affected by “ignore_certificate“ and boths checks - may be active at the same time. - -*certificate*:: [empty] - - The fingerprint of the SSL certificate as a hexadecimal string, you should - not touch it, except if know what you are doing. - -*custom_host*:: [empty] - - A custom host that will be used instead of the DNS records for the server - (anonymous or the jid’s) defined above. - You should not need this in a "normal" use case. - -*custom_port*:: [empty] - - A custom port to use instead of the 5222. - This option can be combined with custom_host. - You should not need this in a "normal" use case. - -*default_nick*:: [empty] - - the nick you will use when joining a room with no associated nick - If this is empty, the $USER environnement variable will be used - -*display_gaming_notifications*:: false - - If set to true, notifications about the games your are playing - will be displayed in the info buffer as 'Gaming' messages. - -*display_tune_notifications*:: false - - If set to true, notifications about the music your contacts listen to - will be displayed in the info buffer as 'Tune' messages. - -*display_mood_notifications*:: false - - If set to true, notifications about the mood of your contacts - will be displayed in the info buffer as 'Mood' messages. - -*display_activity_notifications*:: false - - If set to true, notifications about the current activity of your contacts - will be displayed in the info buffer as 'Activity' messages. - -*display_user_color_in_join_part*:: false - - If set to true, the color of the nick will be used in MUCs information - messages, instead of the default color from the theme. - -*enable_user_activity*:: true - - Set this to false if you don’t want to receive the activity of your contacts - anymore. - -*enable_user_gaming*:: true - - Set this to false if you don’t want to receive the gaming activity of your contacts - anymore. - -*enable_user_mood*:: true - - Set this to false if you don’t want to receive the mood of your contacts - anymore. - -*enable_user_nick*:: true - - Set to false if you don’t want your contacts to hint you their identity. - -*enable_user_tune*:: true - - If this is set to false, you will no longer be subscribed to tune events, - and the display_tune_notifications option will be ignored. - -*enable_vertical_tab_list*:: false - - If true, a vertical list of tabs, with their name, is displayed on the left of - the screen. - -*enable_xhtml_im*:: true - - XHTML-IM is an XMPP extension letting users send messages containing - XHTML and CSS formating. We can use this to make colored text for example. - Set to true if you want to see colored (and otherwise formatted) messages. - -*exec_remote*:: false - - If this is set to true, poezio will try to send the commands to a FIFO - instead of executing them locally. This is to be used in conjunction with - ssh and the daemon.py file. See the /link documentation for details. - -*filter_info_messages*:: [empty] - - A list of words or sentences separated by colons (":"). All the - informational mesages (described above) containing at least one of those - values will not be shown. - -*hide_exit_join*:: -1 - - Exact same thing than hide_status_change, except that it concerns - the quit message, and that it will be hidden only if the value is 0. - Default setting means: - - all quit and join notices will be displayed - -*hide_status_change*:: 120 - - Set a number for this setting. - The join OR status-change notices will be - displayed according to this number. - -1: the notices will ALWAYS be displayed - 0: the notices will NEVER be displayed - n: On any other number, the notices will only be displayed - if the user involved has talked since the last n seconds - if the value is incorrect, -1 is assumed - Default setting means : - - status changes won't be displayed unless - the user talked in the last 2 minutes - -*hide_user_list*:: false - - Whether to hide the list of user in the MultiUserChat tabs or not. Useful - for example if you want to copy/paste the content of the buffer, or if you - want to gain space - -*highlight_on*:: [empty] - - a list of words (separated by a colon (:)) that will be - highlighted if said by someone on a room - -*ignore_certificate*:: false - - Skip certificate validation on connection when _true_. Useful when you are in - anonymous mode and changing servers often. Dangerous in other cases, from a - security perspective. - -*information_buffer_popup_on*:: error roster warning help info - - Some informational messages (error, a contact getting connected, etc) - are sometimes added to the information buffer. These settings can make - that buffer grow temporarly so you can read these information when they - appear. - - A list of message types that should make the information buffer grow - Possible values: error, roster, warning, info, help - -*jid*:: [empty] - - Jabber identifiant. Specify it only if you want to connect using an existing - account on a server. This is optional and useful only for some features, - like room administration or nickname registration. - The 'server' option will be ignored if you specify a JID (Jabber id) - It should be in the form nickname@server.tld - -*lang*:: en - - The lang some automated entities will use when replying to you. - -*lazy_resize*:: true - - Defines if all tabs are resized at the same time (if set to false) - or if they are really resized only when needed (if set to true). - “true” should be the most comfortable value - -*load_log*:: 10 - - The number of line to preload in a chat buffer when it opens. The lines are - loaded from the log files. 0 or a negative value here disable that option. - -*log_dir*:: [empty] - - If log_dir is not set, logs will be saved in $XDG_DATA_HOME/poezio/logs, - i.e. in ~/.local/share/poezio/logs/. So, you should specify the directory - you want to use instead. This directory will be created if it doesn't exist - -*max_lines_in_memory*:: 2048 - - Configure the number of maximum lines (for each tab) that - can be kept in memory. If poezio consumes too much memory, lower these - values - -*max_messages_in_memory*:: 2048 - - Configure the number of maximum messages (for each tab) that - can be kept in memory. If poezio consumes too much memory, lower these - values - -*max_nick_length*:: 25 - - The maximum length of the nickname that will be displayed in the - conversation window. - -*muc_history_length*:: 50 - - Limit the number of messages you want to receive when the - multiuserchat rooms send you recent history - 0: You won't receive any - -1: You will receive the maximum - n: You will receive at most n messages - Note that if you set a huge number (like the default value), you - may not receive that much messages. The server has its own - maximum too. - -*password*:: [empty] - - A password is needed only if you specified a jid. It will be ignored otherwise - If you leave this empty, the password will be asked at each startup - -*plugins_autoload*:: [empty] - - Colon-separated list of plugins to load on startup. - -*plugins_conf_dir*:: [empty] - - If plugins_conf_dir is not set, plugin configs will be loaded from - $XDG_CONFIG_HOME/poezio/plugins. - You can specify another directory to use, it will be created if it - does not exist. - -*plugins_dir*:: [empty] - - If plugins_dir is not set, plugins will be loaded from - $XDG_DATA_HOME/poezio/plugins. - You can specify another directory to use. It will be created if it - does not exist. - -*popup_time*:: 4 - - The time the message will be visible in the information buffer when it - pops up. - If the message takes more than one line, the popup will stay visible - two more second per additional lines. - -*remote_fifo_path*:: ./poezio.fifo - - The path of the FIFO used to send the commands (see the exec_remote option). - -*resource*:: [empty] - - The resource you will use. If it's empty, your resource will be chosen - (most likely randomly) by the server. t is not recommended to use a - resource that is easy to guess, because it can lead to presence leak. - -*rooms*:: poezio@muc.poezio.eu - - the rooms you will join automatically on startup, with associated - nickname or not. - Format : room@server.tld/nickname:room2@server.tld/nickname2 - The default_nick option will be used if "/nickname" is not specified. - -*roster_group_sort*:: name - - How to sort the roster groups. The principles are the same as _roster_sort_ - (see below). - - Available methods are: - * reverse: reverse the current sorting - * name: sort by group name (alphabetical order) - * fold: sort by unfolded/folded - * connected: sort by number of connected contacts - * size: sort by group size - * none: put the "none" group (if any) at the end of the list - -*roster_show_offline*:: false - - Set this to true if you want to display the offline contacts too. - -*roster_sort*:: jid:show - - How you want the contacts to be sorted inside the roster groups. The given - methods are used sequentially (from left to right), so the last one is the - one on the far right. - - Available methods are : - * reverse: reverse the current sorting - * jid: sort by JID (alphabetical order) - * show: sort by show (available/away/xa/…) - * name: sort by roster name (if no name, then the bare jid is used) - * resource: sort by resource number - * online: sort by online presence (online or not) - - Those methods can be arranged however you like, and they have to be - separated by colons (":"). If there are more than 3 or 4 chained - sorting methods, your sorting is most likely inefficient. - -*save_status*:: true - - Save the status automatically in the status and status_message options. - -*send_chat_states*:: true - - if true, chat states will be sent to the people you are talking to. - Chat states are, for example, messages informing that you are composing - a message or that you closed the tab, etc - Set to false if you don't want people to know these information - Note that you won’t receive the chat states of your contacts - if you don't send yours. - -*send_initial_presence*:: true - - Send initial presence (normal behaviour). If false, you will not send nor - receive any presence that is not directed (through /presence) or sent by a - MUC. - -*send_os_info*:: true - - if true, information about the Operation System you're using - will be sent when requested by anyone - Set to false if you don't want people to know these information - Note that this information will not be sent if send_poezio_info is False - -*send_poezio_info*:: true - - if true, information about the software (name and version) - will be sent if requested by anyone - Set to false if you don't want people to know these information - -*send_time*:: true - - if true, your current time will be sent if asked - Set to false if you don't want people to know that information - -*separate_history*:: false - - If true, the history of inputs of the same nature won’t be shared - between tabs (as in weechat). - -*server*:: anon.jeproteste.info - - The server to use for anonymous authentication. - Make sure it supports anonymous authentification. - Note that this option doesn’t do anything at all if you’re using your own JID. - -*show_inactive_tabs*:: true - - If you want to show all the tabs in the Tab bar, even those - with no activity, set to true. Else, set to false - -*show_muc_jid*:: true - - Set this to false if you want to display only the “user” part of the MUC - jid. E.g. if you have poezio@muc.poezio.eu, it will be displayed as - `poezio`. This will be used only if use_tab_nicks is set to true. - -*show_roster_jids*:: true - - Set this to false if you want to hide the JIDs in the roster (and keep only - the contact names). If there is no contact name, the JID will still be - displayed. - -*show_s2s_errors*:: true - - Show s2s errors in the roster or not. - -*show_tab_names*:: false - - If you want to show the tab name in the bottom Tab bar, set this to true. - -*show_tab_numbers*:: true - - If you want to disable the numbers in the bottom Tab bar, set this to false. - Note that if both show_tab_names and show_tab_numbers are set to false, the - numbers will still be displayed. - -*show_timestamps*:: true - - Whether or not to display a timestamp before each message. - -*status*:: [empty] - - The status (show) poezio will send when connecting. It can be available, - dnd,chat, xa or away. - Nothing or an invalid value will mean available. - -*status_message*:: [empty] - - The status message poezio will send when connecting. - -*use_bookmark_method*:: [empty] - - the method that poezio will use to store your bookmarks online. - Possible values are: privatexml, pep. - You should not have to edit this in a normal use case. - -*use_log*:: true - - Set to 'false' if you don’t want to save logs of all the messages - in files. - -*use_pep_nick*:: true - - Use the nickname broadcasted by the user if set to true, and if none - has already been set manually. - -*use_remote_bookmarks*:: true - - Use this option to force the use of local bookmarks if needed. - Anything but "false" will be counted as true. - -*use_tab_nicks*:: true - - The tabs have a name, and a nick, which is, for a contact, its name in the - roster, or for a private conversation, the nickname in the MUC. Set this to - true if you want to have them shown instead of the jid of the contact. - -*theme*:: [empty] - - The name of the theme file (without the .py extension) that will be used. - The file should be located in the theme_dir directory. - If the file is not found (or no filename is specified) the default - theme will be used instead - -*themes_dir*:: [empty] - - If themes_dir is not set, themes will searched for in - $XDG_DATA_HOME/poezio/themes, i.e. in ~/.local/share/poezio/themes/. - So you should specify the directory you want to use instead. - This directory will be created at startup if it doesn't exist - -*user_list_sort*:: desc - - If set to desc, the MUC users will be displayed from top to bottom in the list, - if set to asc, they will be displayed from bottom to top. - -*vertical_tab_list_size*:: 20 - - Size of the vertical tab list. - -*vertical_tab_list_sort*:: desc - - If set to desc, the tabs will be displayed from top to bottom in the list, - if set to asc, they will be displayed from bottom to top. - -*whitespace_interval*:: 300 - - Interval of the whitespace keepalive sending to the server. - 300 should be fine, but change it if some services have a stricter policy - on client inactivity. - -*words*:: [empty] - - Personal dictionary of the words you use often, that you want to complete - through recent words completion. They must be separated bu a colon (:). That - completion will work in chatrooms, private conversations, and direct - conversations. - - -Optional section options -~~~~~~~~~~~~~~~~~~~~~~~~ -These option can appear in optional sections. These section are named -after a JID. These option will apply only for the given JID. For example -if an option appears in a section named [user@example.com], it will -apply only for the conversations with user@example.com. - -If an option appears in a section named [@example.com], it will apply -for all the conversations with people @example.com, except when the option -is already defined in a [user@example.com] section. - -The priority of settings is thus like this: -user@example.com > @example.com > Poezio (more specific to less specific) - -Note that some of these options can also appear in the global section, -they will be used as a fallback value when no JID-specific option is -found. - -.foo is _true_ for *user@example.com* but is _false_ for everyone else -============================================ -[source,conf] -------------- -[Poezio] -foo = false -[user@example.com] -foo = true -[@example.com] -bar = false -------------- -============================================ - -[horizontal] -*autorejoin*:: false - - Set to 'true' if you want to automatically rejoin the - room when you're kicked or banned. - -*autorejoin_delay*:: 5 - - Set to the number of seconds before reconnecting after getting kicked or - banned. 0, a negative value, or no value means instant reconnection. - This option only works if autorejoin is enabled. - -*disable_beep*:: false - - Disable the beeps triggered by this conversation. Works in MucTab, - PrivateTab and ConversationTab. - -*display_activity_notifications*:: false - - If set to true, notifications about the current activity of your contacts - will be displayed in the info buffer as 'Activity' messages. - -*display_gaming_notifications*:: false - - If set to true, notifications about the game your are playing - will be displayed in the info buffer as 'Gaming' messages. - - -*display_mood_notifications*:: false - - If set to true, notifications about the mood of your contacts - will be displayed in the info buffer as 'Mood' messages. - -*display_user_color_in_join_part*:: false - - If set to true, the color of the nick will be used in MUCs information - messages, instead of the default color from the theme. - -*display_tune_notifications*:: false - - If set to true, notifications about the music your contacts listen to - will be displayed in the info buffer as 'Tune' messages. - -*hide_exit_join*:: -1 - - Exact same thing than hide_status_change, except that it concerns - the quit message, and that it will be hidden only if the value is 0. - Default setting means: - - all quit and join notices will be displayed - -*hide_status_change*:: 120 - - Set a number for this setting. - The join OR status-change notices will be - displayed according to this number. - -1: the notices will ALWAYS be displayed - 0: the notices will NEVER be displayed - n: On any other number, the notices will only be displayed - if the user involved has talked since the last n seconds - if the value is incorrect, -1 is assumed - Default setting means : - - status changes won't be displayed unless - the user talked in the last 2 minutes - -*highlight_on*:: [empty] - - a list of words (separated by a colon (:)) that will be - highlighted if said by someone on a room - -*ignore_private*:: false - - Ignore private messages sent from this room. - -*load_log*:: 10 - - The number of line to preload in a chat buffer when it opens. The lines are - loaded from the log files. 0 or a negative value here disable that option. - No value makes poezio fall back to the global value. - -*password*:: [empty] - - The password needed to join the room. - -*private_auto_response*:: "Not in private, please." - - The message you want to be sent when someone tries to message you. - -*send_chat_states*:: true - - Lets you disable/enable chatstates per-JID. Works in MucTab, PrivateTab - and ConversationTab. - -*show_useless_separator*:: false - - If true, show the separator in a chat room, even if no one spoke. - -*use_log*:: [empty] - - Use logs for this JID or not. No value will make poezio fall back to the - global value. - -*notify_messages*:: true - - Only for MUC tabs: if true the tab will change its color to notify you when a new message is received. You will still be notified of highlights. Set to false if you’re not interested in a room non-highlight notifications. diff --git a/doc/en/dev/contributing.txt b/doc/en/dev/contributing.txt deleted file mode 100644 index 6dbda93e..00000000 --- a/doc/en/dev/contributing.txt +++ /dev/null @@ -1,71 +0,0 @@ -Contributing -============ - -Conventions ------------ - -We don’t have a strict set of conventions, but you should respect PEP8 mostly -(e.g. 4 spaces, class names in CamelCase and methods lowercased with -underscores) except if it means less-readable code (80 chars is often a hassle, -and if you look inside poezio you’ll see lots of long lines, mostly because of -strings). - - -As explained in the link:./overview.html[overview], “global” code goes in -_core.py_, tab-related code goes in _tabs.py_, and ui-related code goes in -_windows.py_. There are other modules (e.g. xhtml.py) but they do not matter -for the application as a whole. - -Commit guidelines ------------------ - -Commits _should_ have a meaninful title (first line), and _may_ have a detailed -description below. There are of course exceptions (for example, a single-line -commit that takes care of a typo right behind a big commit does not need to -say “fix a typo ("azre" → "are") in toto.py line 45454", since the metainfos -already take care of that.), but if you do not have commit access on the -poezio trunk, you can still reset and commit again. - - -Try to do atomic commits: since git is a DVCS, it doesn’t hurt to git add -p -and split the commit into several meaningful small commits ; on the contrary, -it helps to track the changes on different levels. - - -If you have a conflict, solve it with rebase and not merge if the fast-forwards -do not resolve it automatically in your case. This helps to avoid creating -useless merges (and polluting the commit history) when none is needed. - -.Basic case -========================== - - git fetch origin - git rebase origin/master - git push origin master - -========================== - -If your commit is related to an issue on -link:https://dev.louiz.org/project/poezio/bugs[our tracker] (or fixes such an - issue), you can use “Fixes #BUGID” or “References #BUGID” to help with the - tracking. - - -Getting your code into poezio ------------------------------ - -If you have code you want to contribute, you can: - -* Give us a patch and a description of what it does -* Give us a link to a _git_ repo from which we can pull - -The code is of course reviewed and tested a bit, but we trust the contributors -to submit good code. If we can’t integrate the given code into poezio (if it -crashes or has some issues), if the size is small, we may tweak it ourselves -and integrate it, and if not, you are of course free to take our advice into -account and submit it again. - - -If you have already submitted some code and plan to do more, you can ask us - direct commit access on the main repo. - diff --git a/doc/en/dev/index.txt b/doc/en/dev/index.txt deleted file mode 100644 index 17ca42d6..00000000 --- a/doc/en/dev/index.txt +++ /dev/null @@ -1,8 +0,0 @@ -Development -=========== - -This section of the documentation is here to provide a quickstart for someone -willing to start hacking poezio. - -* link:overview.html[Overview] -* link:contributing.html[Contributing] diff --git a/doc/en/dev/overview.txt b/doc/en/dev/overview.txt deleted file mode 100644 index 7f9f9445..00000000 --- a/doc/en/dev/overview.txt +++ /dev/null @@ -1,106 +0,0 @@ -Overview -======== - -NOTE: This is not an introduction to XMPP, but to poezio - - -Global overview ---------------- - -Poezio is an application that has three main layers, mostly separated in three -different python modules: _core_, _tabs_, and _windows_. An UML diagram of -Poezio would be inneficient, cluttered, or incomplete, so there is none, if -that bugs you. - -image::../../images/layers.png["The application layers", title="Layers"] - -_Core_ is mostly a “global” object containing the state of the application at -any time, it contains the global commands, the xmpp event handlers, the list -of open tabs, etc. Most objects in poezio have a self.core attribute -referencing the _Core_ (it’s a singleton, so there is never more than one -instance). _Core_ also contains the main loop of the application, which then -dispatchs the I/O events (keypress) to the appropriate methods. - - -But the main loop is not the most important thing in poezio; because it is an -IM client, it is essentially event-driven. The event part is handled by -SleekXMPP, which is the library we chose after moving away from xmpppy. - - -_Tabs_ are the second layer of poezio, but the first dealing with the UI: each -_Tab_ is a layout of several _windows_, it contains tab-specific commands, -tab-specific keybinds, and it has methods in order for core to -interact with it, and some methods are only proxies for the methods of a -_window_ - -Example scenario: If someone presses the key PageUp, then Core will call the -appropriate method on the current _Tab_, which will in turn, if it implements the -method (inherited empty from the Tab class), call a scrolling method from the -appropriate _window_. - -All tabs types inherit from the class _Tab_, and the _Tabs_ featuring -chat functionnality will inherit fro _ChatTab_ (which inherits from _Tab_). - -Examples of _Tabs_: MUCTab, XMLTab, RosterTab, MUCListTab, etc… - -Event handlers --------------- - -The events handlers are registered right at the start of poezio, and then -when a matching stanza is received, the handler is called in a separate thread -from the main loop. The handlers are in _Core_, and then they call the -appropriate methods in the corresponding _tabs_. - -Example scenario: if a message is received from a MUC, then the _Core_ handler -will identify the _Tab_, and call the relevant handler from this _Tab_, this tab -will in turn, add the message to the buffer, which will then add it to the -relevant _windows_. - -NOTE: All the _windows_ that deal with received or generated text are linked -to a _text_buffer_, in order to rebuild all the display lines from the -sources if necessary. This also enables us to have several _windows_ -presenting the same text, even if they are not of the same size and layout. - - -Commands and completion ------------------------ - -Commands are quite straightforward: those are methods that take a string as a -parameter, and they do stuff. - -From an user point of view, the methods are entered like that: - -================================== - - /command arg1 arg2 - -or - - /command "arg1 with spaces" arg2 - -================================== - -However, when creating a command, you wil deal with _one_ str, no matter what. -There are utilities to deal with it (common.shell_split), but it is not always -necessary. Commands are registered in the _commands_ dictionnary of a tab -structured as key (command name) -> tuple(command function, help string, completion). - - -Completions are a bit tricky, but it’s easy once you get used to it: - -They take an _Input_ (a _windows_ class) as a parameter, named the_input -everywhere in the sources. To effectively have a completion, you have to call -_the_input.auto_completion()_ at the end of the function. - -*the_input.auto_completion(completion_list, after='', quote=True)*: -Set the input to iterate over _completion_list_ when the user hits tab, insert -_after_ after the completed item, and surround the item with double quotes or -not. - -There is no method to find the current argument in the input (although the -feature is planned), so you have to assume the current argument is the last, -and guess it by splitting the string an checking for end-space. - -You can look for examples in the sources, all the possible cases are -covered (single-argument, complex arguments with spaces, several arguments, -etc…) diff --git a/doc/en/index.txt b/doc/en/index.txt deleted file mode 100644 index 1a538f0b..00000000 --- a/doc/en/index.txt +++ /dev/null @@ -1,21 +0,0 @@ -Poezio Documentation -==================== - -Welcome to the english documentation, here is a list of the available pages. - -Available pages ---------------- - - -* link:install.html[Installation] -* link:configure.html[Configuration] -* link:ssl.html[SSL Management] -* link:usage.html[Usage] -* link:themes.html[Theming] -* link:keys.html[Keys] -* link:plugins/index.html[Available Plugins] -* link:misc/index.html[Other topics] -* link:plugins.html[Developing plugins] -* link:dev/index.html[Developing Poezio] -* link:xep.html[Current XEP support] -* link:dev/index.html[Contributing] diff --git a/doc/en/install.txt b/doc/en/install.txt deleted file mode 100644 index 78b4a8aa..00000000 --- a/doc/en/install.txt +++ /dev/null @@ -1,118 +0,0 @@ -Install -======= - -NOTE: Python 3.2 or better is highly recommended, as we do not officially -support python 3.1 (although we do try to keep things running). - - -Poezio in the GNU/Linux distributions -------------------------------------- - -As far as I know, Poezio is available in the following distributions, you just - have to install it by using the package manager of the distribution, if you're - using one of these. - -* *Archlinux*: A poezio and poezio-git packages are in AUR (use your favourite - AUR wrapper to install them) -* *Gentoo*: https://github.com/sekh/sekh_overlay[Sekh’s overlay] contains - everything required to build poezio (sleekxmpp, dnspython, and poezio) -* *Debian*: Use an other distro. - -(If an other distribution provides a poezio package, please tell us and we will - add it to the list) - - -Install poezio from the sources -------------------------------- - -You can download poezio's https://dev.louiz.org/project/poezio/download[stable - sources] or fetch the development version (trunk), using git: -============================ -git clone https://git.louiz.org/poezio -============================ - -NOTE: To clone the repo, which uses a self-signed certificated, you can -prefix the clone command with GIT_SSL_NO_VERIFY=1. - -In order for poezio to correctly work, you need the libs SleekXMPP and - dnspython. You can install them by downloading it from the - https://github.com/fritzy/SleekXMPP/[SleekXMPP] page and the - http://www.dnspython.org/[dnspython] page , but you'll need the development - version of SleekXMPP. Alternatively, you can download poezio's sources - including SleekXMPP and dnspython, that's the easier way. - -=== Dependencies === - -NOTE: If your python3 version is too old because of debian (e.g. < 3.2), you -should install the python3-argparse package if it exists, or use -pip3/virtualenvs to install it. - -If you want to install SleekXMPP and dnspython by yourself, follow these - instructions. Else, go to the next section (recommended). - - -Download SleekXMPP -============================ -git clone git://github.com/fritzy/SleekXMPP.git -============================ - -Make sure you're using the develop branch by typing -============================ -cd SleekXMPP - -git checkout develop -============================ - -Install SleekXMPP with -============================ -python3 setup.py build - -su -c "python3 setup.py install" -============================ - -Install the dnspython3 package on your distribution or install it manually: -============================ -wget -O dnspython.tgz http://www.dnspython.org/kits3/1.10.0/dnspython3-1.10.0.tar.gz - -tar xvf dnspython.tgz - -cd dnspython3-1.10.0 -============================ - -And do the same again: -============================ -python3 setup.py build - -su -c "python3 setup.py install" -============================ - - -=== Poezio installation === - -If you skipped the installation of the dependencies and you only want to test - poezio without a system-wide install, do, in the _poezio_ directory: -============================ -sh update.sh -============================ - -If you have git installed, it will download and update locally the - libraries for you. - - -If you don't want to install poezio but just test it (or keep a development - version), do: -============================ - ./launch.sh -============================ - - -To install poezio, do, as root (or sudo with ubuntu or whatever): -============================ -make install -============================ - -And then start it with: -============================ -poezio -============================ - diff --git a/doc/en/keys.txt b/doc/en/keys.txt deleted file mode 100644 index f83a3660..00000000 --- a/doc/en/keys.txt +++ /dev/null @@ -1,424 +0,0 @@ -Keys -==== - -This file describes the default keys of poezio and explains how to -configure them. - -By default, most keys manipulating the input (where you type your -messages and commands) behave like emacs does. - -NOTE: keys are case sensitive. Ctrl-X is not the same than Ctrl-x - - -Key bindings listing --------------------- -Some key bindings are available only in some tabs, others are global. - - -Global keys -~~~~~~~~~~~ -These keys work in *any* tab. - -*Ctrl-n*:: Go to the next tab. - -*Ctrl-p*:: Go to the previous tab. - -*Alt-number*:: Go to the tab with that number. - -*Alt-j*:: Waits for you to type a two-digits number. Go to tab number xx. - -*Alt-e*:: Go to the tab with a higher priority (private message > - highlight > message > non-empty input). - -*Alt-z*:: Go to the previously selected tab. - -*Alt-r*:: Go to the roster tab. - -*F7*:: Shrink the information buffer. - -*F8*:: Grow the information buffer. - -*Ctrl-l*:: Refresh the screen. - -*Alt-D*:: Scroll the information buffer up. - -*Alt-C*:: Scroll the information buffer down. - -Input keys -~~~~~~~~~~ -These keys concern only the inputs. - -NOTE: The clipboard is common to all inputs. This lets you cut a text -from one input to paste it into an other one. - -*Ctrl-a*:: Move the cursor to the beginning of line. - -*Ctrl-e*:: Move the cursor to the end of line. - -*Ctrl-u*:: Delete the text from the start of the input until the cursor - and save it to the clipboard. - -*Ctrl-k*:: Delete the text from the cursor until the end of the input - and save it to the clipboard. - -*Ctrl-y*:: Insert the content of the clipboard at the cursor position. - -*Ctrl-Enter*:: Insert a line break. Since the input is only one line, - the line break is represented by the character _|_ in it but will be - sent as the real _\n_ character. - - -Chat tab input keys -~~~~~~~~~~~~~~~~~~~~~ -These keys work in any conversation tab (MultiUserChat, Private or -Conversation tabs). - -*Key Up*:: Use the previous message from the message history. - -*Key Down*:: Use the next message from the message history. - -*Page Up*:: Scroll up in the conversation by x lines, where x is the -height of the conversation window - 1. - -*Page Down*:: Like Page Up, but down. - -*Ctrl-b*:: Go one line up in the buffer. - -*Ctrl-f*:: Go one line down in the buffer. - -*Ctrl-s*:: Go half a screen up in the buffer. - -*Ctrl-x*:: Go half a screen down in the buffer. - -*Alt-/*:: Complete what you’re typing using the "recent" words from the - current conversation, if any. - -*Alt-v*:: Move the separator at the bottom of the tab. - -*Alt-h*:: Scroll to the separator, if there is one. - -MultiUserChat tab input keys -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -These keys work only in the MultiUserChat tab. - -*Alt-u*:: Scroll the user list down. - -*Alt-y*:: Scroll the user list up. - -*Alt-p*:: Scroll to the previous highlight. - -*Alt-n*:: Scroll to the next highlight. - -*tabulation*:: Complete a nick. - -*Ctrl-c*:: Insert xhtml formatting. You have to press Ctrl-c then a character - listed below: -- 1: Red -- 2: Green -- 3: Yellow/Orange -- 4: Blue -- 5: Pink -- 6: Turquoise -- b: Bold -- o: Stop formatting - - -MultiUserChat List tab input keys -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -These keys work only in the MultiUserChat List tab (obtained with /list ). - -*Up*:: Go up one row. - -*Down*:: Go down one row. - -*j*:: Join the MultiUserChat currently selected. - -*J*:: Join the MultiUserChat currently selected, without giving focus to iuts tab. - -*Ctrl-M*:: Join the MultiUserChat currently selected (same as "j"). - -*PageUp*:: Scroll a page of chats up. - -*PageDown*:: Scroll a page of messages down. - - -Roster tab input keys -~~~~~~~~~~~~~~~~~~~~~ - -These keys work only in the Roster tab (the tab number 0). - -*/*:: Open a prompt for commands. - -*s*:: Start a search on the contacts. - -*S*:: Start a (slow) search with approximation on the contacts. - -*Alt-u*:: Move the cursor to the next group. - -*Alt-y*:: Move the cursor to the previous group. - -*Ctrl-c*:: Cancel the input (search or command) - -NOTE: The following will not work if you can still write things in the -input (meaning you previously typed _s_ or _/_): - -*Space*:: Fold/Unfold the current item. - -*Up*:: Move the cursor down one contact. - -*Down*:: Move the cursor up one contact. - -*o*:: Show the offline contacts. - -*PageUp*:: Scroll a page of contacts up. - -*PageDown*:: Scroll a page of contacts down. - - -Data Forms tab keys -~~~~~~~~~~~~~~~~~~~ -*Ctrl+y*:: Validate the form, send it and close the tab. - -*Ctrl+g*:: Cancel that form (do not send your changes) and close the - tab. - -*Up*:: Select the next field. - -*Down*:: Select the previous field. - -*Right/Left*:: Switch between possible values, in a jid-multi, - list-multi, list-single or text-multi field. - -*Space*:: Select that option - - -MultiUserChat List tab input keys -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -These keys work only in the MultiUserChat List tab (obtained with /list -). - -*Up*:: Go up one row. - -*Down*:: Go down one row. - -*j*:: Join the MultiUserChat currently selected. - -*J*:: Join the MultiUserChat currently selected, without giving focus to - iuts tab. - -*Ctrl-M*:: Join the MultiUserChat currently selected (same as _j_). - - -XML tab input keys -~~~~~~~~~~~~~~~~~~ - -These keys only work in the XML tab (obtained with /xml_tab) - -*Ctrl+k*:: Freeze or un-freeze the display in order to have a clear view of - the stanzas. - - - -Key configuration ------------------ -Bindings are keyboard shortcut aliases. You can use them -to define your own keys to replace the default ones. -where _^x_ means _Control + x_ -and _M-x_ means _Alt + x_ - -To know exactly what the code of a key is, just run -================== -python3 src/keyboard.py -================== -And enter any key. - -.Turn Alt-i into a tab key (completion, etc) -================== -M-i = ^I -================== - -Actions -------- - -Mapping actions on keys -~~~~~~~~~~~~~~~~~~~~~~~ - -One may want to add keyboard shortcuts on actions that were not mapped already -in poezio. To this effect, you can map the keys on actions using the _Key -configuration_ seen in the previous section. - - -The actions are pseudo-keystrokes, and have to be treated the same way. -They all begin with an underscore to prevent any possible collision with things - already defined. - -Actions list -~~~~~~~~~~~ - -NOTE: Even if some of these actions are labelled as similar to other -keystrokes, remapping the keystrokes will not remap the actions defined here. - -[horizontal] -*_bookmark*:: Bookmarks the current room. - - Similar to /bookmark. - -*_bookmark_local*:: Bookmarks the current room, locally. - - Similar to /bookmark_local - -*_close_tab*:: Closes the current tab. - - This is the same as /close. The first tab (the roster) can not be closed. - -*_disconnect*:: Disconnects poezio from the server. - -*_quit*:: Exits poezio. - - Similar to /quit. - -*_reconnect*:: Disconnects then reconnects poezio, if possible. - - This is similar to /connect. - -*_redraw_screen*:: Redraws the screen. - - This isn’t normally useful, similar to Ctrl-l. - -*_reload_theme*:: Reloads the theme. - - Similar to /theme. - -*_remove_bookmark*:: Removes the bookmark on the current room. - - Similar to /remove_bookmark. - -*_room_left*:: Goes to the room on the left. - - Similar to Ctrl-p. - -*_room_right*:: Goes to the room on the right. - - Similar to Ctrl-n. - -*_show_roster*:: Goes to the roster. - - Similar to Alt-r. - -*_scroll_down*:: Scrolls down in the current buffer. - - Similar to PAGEDOWN. - -*_scroll_up*:: Scrolls up in the current buffer. - - Similar to PAGEUP. - -*_scroll_info_down*:: Scrolls down in the info buffer. - - Similar to Alt-c. - -*_scroll_info_up*:: Scrolls up in the info buffer. - - Similar to Alt-d. - -*_server_cycle*:: Cycles in the current MUC server. - - Similar to /server_cycle in a MUC. If you are not in a MUC, you will get - an error. - -*_show_bookmarks*:: Shows the current bookmarks. - - Similar to /bookmarks. - -*_show_important_room*:: Goes to the most important room. - - Similar to Alt-e. - -*_show_invitations*:: Shows all the pending MUC invitations. - - Similar to /invitations. - -*_show_plugins*:: Shows the currently loaded plugins. - - Similar to /plugins. - -*_show_xmltab*:: Opens an XML tab. - - Similar to /xml_tab. - -*_toggle_pane*:: Toggles the left pane. - - Similar to F4. - -Status actions -~~~~~~~~~~~~~~ - -[horizontal] -*_available*:: Sets the status to _available_. - - Similar to /status available. - -*_away*:: Sets the status to _away_. - - Similar to /status away. - -*_chat*:: Sets the status to _chat_. - - Similar to /status chat. - -*_dnd*:: Sets the status to _dnd_. - - Similar to /status dnd. - -*_xa*:: Sets the status to _xa_. - - Similar to /status xa. - -Command execution -~~~~~~~~~~~~~~~~~ - -With that kind of actions, you can also execute arbitrary commands, with the - __exc__ keyword. - - -You only have to prefix your command line with *\_exc\_*, and without the _/_. - -./kick Partauche added on Ctrl-w -======================== - - ^W = _exc_kick Partauche - -======================== - -That key binding will only work in the tabs defining the command (here, the -MUC tab), and will show an error message in the others. - -Examples -~~~~~~~~ - -.Config with user-defined actions -================================= -[source,conf] -------------- -[bindings] -^W = _close_tab -M-x = _show_xmltab -M-i = _show_important_room -M-p = _toggle_pane -------------- -================================= - -.Config with commands mapped -================================= -[source,conf] -------------- -[bindings] -M-c = _exc_configure -^Q = _exc_part RAGE QUIT -^J = _exc_join -^F = _exc_load figlet -^R = _exc_load rainbow -^S = _exc_say llollllllllllll -------------- -================================= diff --git a/doc/en/misc/correct.txt b/doc/en/misc/correct.txt deleted file mode 100644 index eadcde2b..00000000 --- a/doc/en/misc/correct.txt +++ /dev/null @@ -1,21 +0,0 @@ -Message Correction -================== - -Poezio implements the link:http://xmpp.org/extensions/xep-0308.html[XEP-0308] -which allows the correction of the last message sent. - -The corrections are signalled with a number append to the nick of the user, in -a different color. - -image::../../images/correct.png["Corrected message", title="A corrected message"] - -The *9* here represents the number of times this message has been corrected. - - -You can show the revisions of a message by loading the -link:../plugins/display_corrections.html[display_corrections] plugin, and you -can correct your own messages with the */correct* command. - - -NOTE: Please do not abuse of this feature, as it will simply be displayed as -another message in the other clients. diff --git a/doc/en/misc/index.txt b/doc/en/misc/index.txt deleted file mode 100644 index 7eaecf5f..00000000 --- a/doc/en/misc/index.txt +++ /dev/null @@ -1,9 +0,0 @@ -Other topics -============ - -Available pages in this topic ------------------------------ - - -* link:correct.html[Message Correction] -* link:separate.html[Using several accounts] diff --git a/doc/en/misc/separate.txt b/doc/en/misc/separate.txt deleted file mode 100644 index 76db8877..00000000 --- a/doc/en/misc/separate.txt +++ /dev/null @@ -1,20 +0,0 @@ -Using several accounts -====================== - -Poezio does not support multi-accounts, and we do not plan to do so in a -foreseeable future. However, you can run several poezio instances (e.g. with -tmux or screen) to have similar functionnality. - -You can specify a different configuration file than the default with: - -[source, bash] - ./launch.sh -f separate_config.cfg - - -The relevant options for a separate config are the following: - -* *plugins_dir*: A different directory for the plugin sources (not _that_ useful) -* *log_dir*: A different directory for logs -* *plugins_conf_dir*: A different directory for plugin configurations ; useful for the GPG plugin, for example. - -Those options are detailed in the link:../configure.html[configuration page]. diff --git a/doc/en/plugins.txt b/doc/en/plugins.txt deleted file mode 100644 index 3e8a0447..00000000 --- a/doc/en/plugins.txt +++ /dev/null @@ -1,388 +0,0 @@ -Plugins -======= - -Location --------- - -The plugins have to be present in '$XDG_DATA_HOME/poezio/plugins/plugin_name.py' -(or '~/.local/share' if not defined) - -Structure ---------- - -A plugin must always be a class named Plugin that inherits the -plugin.BasePlugin class defined into the *plugin* poezio module. - -Methods -------- - -Overridden methods -~~~~~~~~~~~~~~~~~~ -The *Plugin* class has several method that you can override for your own - convenience - -[[init]] -*init*:: +self+ + -This method is called when the plugin is loaded, this is where you call -the other methods, for example <>, and initialize -everything to make your plugin actually do something. <>, - <> - -*cleanup*:: +self+ + -Called when the plugin is unloaded (or when poezio is exited). Clean everything -that needs to be cleaned here. - -Callable methods -~~~~~~~~~~~~~~~~ -The BasePlugin has several methods that can be used. Here is a list of -all its methods that you could use in your plugin, describing what they -do, their arguments, and giving some example for each of them. - -[[add-command]] -*add_command*:: +self+, +name+, +handler+, +help+, +completion=None+ + -This method adds a global command to poezio. For example you can add a /foo -command that the user could call when the plugin is loaded, by calling this -method with _foo_ as its _name_ argument. <> - -* _name_: (string) the name of the command (for example, if it is 'plugintest', - it can add a /plugintest command) -* _handler_: (function) the function to be called when the command is executed. -the handler takes *args* as a parameter, which is a string of what -is entered after the command. Split *args* (with _common.shell_split_) to use -that as command arguments. -* _help_: (string) the help message available for that command through the - _/help_ command. -* _completion_: (function) the completion for the args of that command. It - takes an input object as its only argument. This function should call the -_auto_completion()_ method on the input object, passing a list of possible - strings for the completion and returning the value of that call directly. -Everything else is handled by that _auto_completion()_ method (checking what - strings match, how to cycle between matches, etc). If you don’t want any - special completion for that command, just pass None (the default value). - -*del_command*:: +self+, +name+ + -This method removes a command added by your plugin. - -* _name_: (string) the name of the command you want to remove. - -*add_key*:: +self+, +key+, +handler+ + -This method adds a global keyboard shortcut on _key_ that will call _handler_. -You can get the keys with _python3 src/keyboard.py_. - -* _key_: String representing the key press in curses. -* _handler_: Method called whenever _key_ is pressed. - -*del_key*:: +self+, +key+ + -This method deletes a keyboard shortcut previously added by your plugin. - -* _key_: String representing the key press in curses. - -*add_tab_key*:: +self+, +tab_type+, +key+, +handler+ + -This method adds a tab-custom command to poezio. For example you can add _^G_ -keybind that the user could call in a specific tab when the plugin is loaded. - -* _tab_type_: You have to _import tabs_ in order to get tabs types. The - following are possible: -** _tabs.MucTab_: The MultiUserChat tabs -** _tabs.PrivateTab_: The Private tabs -** _tabs.ConversationTab_: The Roster tab -** _tabs.RosterInfoTab_: The MultiUserChat, Private, and Conversation tabs -** _tabs.ChatTab_: The MultiUserChat, Private, and Conversation tabs -** _tabs.MucListTab_: The MultiUserChat list tabs -* _key_: (string) the curses representation of the keypress (see above). -* _handler_: (function) the handler to be called when the keypress is found. - -*del_tab_command*:: +self+, +tab_type+, +key+ -This method removes a tab command added by your plugin. - -* _key_: (string) the name of the keybind you want to remove. -* _tab_type_: the type of tab (see help for _add_key_command_) - -*add_tab_command*:: +self+, +tab_type+, +name+, +handler+, +help+, +completion+ + -This method adds a tab-custom command to poezio. For example you can add a /dou -command that the user could call in a specific tab when the plugin is loaded. - -* _tab_type_: You have to _import tabs_ in order to get tabs types. The - following are possible: -** _tabs.MucTab_: The MultiUserChat tabs -** _tabs.PrivateTab_: The Private tabs -** _tabs.ConversationTab_: The Roster tab -** _tabs.RosterInfoTab_: The MultiUserChat, Private, and Conversation tabs -** _tabs.ChatTab_: The MultiUserChat, Private, and Conversation tabs -** _tabs.MucListTab_: The MultiUserChat list tabs -* _name_: (string) the name of the command (for example, if it is 'plugintest', - it can add a /plugintest command) -* _handler_: (function) the function to be called when the command is executed. -the handler takes *args* as a parameter, which is a string of what -is entered after the command. Split *args* (with _common.shell_split_) to use -that as command arguments. -* _help_: (string) the help message available for that command through the - _/help_ command. -* _completion_: (function) the completion for the args of that command. It - takes an input object as its only argument. This function should call the -_auto_completion()_ method on the input object, passing a list of possible - strings for the completion and returning the value of that call directly. -Everything else is handled by that _auto_completion()_ method (checking what - strings match, how to cycle between matches, etc). If you don’t want any - special completion for that command, just pass None (the default value). - -*del_tab_command*:: +self+, +tab_type+, +name+ -This method removes a tab command added by your plugin. - -* _name_: (string) the name of the command you want to remove. -* _tab_type_: the type of tab (see help for _add_tab_command_) - -*add_event_handler**: +self+, +event_name+, +handler+ +position+ -This methods adds a callback that will be called whenever the given event -occurs. <> - -* _event_name_: (string) The name of the event you want to ``monitor''. -This can be a sleekxmpp event, or a poezio event. See the list of -<>. -* _handler_: The method that will be called whenever the event occurs. -It must accept the arguments specified for that event in the - <>. -* _position_: Optional, this argument will specify the position of the handler - in the handler list for this event. It is 0 by default, and will only be used - with the internal poezio events described below. - - - -Attributes ----------- - -Config -~~~~~~ -By default, each plugin has a PluginConfig object accessible with *self.config*. - -*PluginConfig.read*:: +self+ + -Reads the config file from $XDG_CONFIG_HOME/poezio/plugins/plugin_name.cfg, it - is called upon initialization, so you should not need it. - -*PluginConfig.write*:: +self+ + -Writes the config to the same file mentioned previously. - -Core -~~~~ -Each plugin has a reference to the Core object accessible with *self.core*, - that allows you to do about anything with poezio. Remember to use it only when - you need it, and to use the functions described in this documentation only, - even if much more is available. If your plugin needs to do something not - available with these methods, please do a feature request instead of doing - some dirty hacks with some other methods. - -Core methods -^^^^^^^^^^^^ -CAUTION: TODO - - -[[events-list]] -Events list ------------ - -Poezio events -~~~~~~~~~~~~~ - -*muc_say*:: +message+, +tab+ + -The handlers for this event are called whenever you say something in a MUC - (through the /say command or by direct input). The parameters given to the - handlers are: - -* _message_: Message to be sent. -* _tab_: Tab in which the message will be sent. - -*muc_say_after*:: +message+, +tab+ + -The handlers for this event are called whenever you say something in a MUC - (through the /say command or by direct input). The difference with muc_say is - just that *muc_say_after* hook is called AFTER the xhtm-im body has been - generated. So you *MUST* not insert any color attribute in the body using this - hook. The hook is less safe that *muc_say* and most of the time you should not - use it at all. The parameters given to the handlers are: - -* _message_: Message to be sent. -* _tab_: Tab in which the message will be sent. - -*private_say*:: +message+, +tab+ + -The handlers for this event are called whenever you say something in a private - conversaton in a MUC (through the /say command or by direct input). The - parameters given to the handlers are: - -* _message_: Message to be sent. -* _tab_: Tab in which the message will be sent. - -*private_say_after*:: +message+, +tab+ + -The handlers for this event are called whenever you say something in a MUC - (through the /say command or by direct input). The difference with private_say - is just that *private_say_after* hook is called AFTER the xhtm-im body has - been generated and the message has been displayed on the conversation, this - means that if you modify the body, the message that will be sent will not be - the same that the one displayed in the text buffer. So you *MUST* not insert - any color attribute in the body using this hook. The hook is less safe that - *private_say* and most of the time you should not use it at all. The - parameters given to the handlers are: - -* _message_: Message to be sent. -* _tab_: Tab in which the message will be sent. - -*conversation_say*:: +message+, +tab+ + -The handlers for this event are called whenever you say something in direct - conversation (through the /say command or by direct input). The parameters - given to the handler are: - -* _message_: Message to be sent. -* _tab_: Tab in which the message will be sent. - -*conversation_say_after*:: +message+, +tab+ + -The handlers for this event are called whenever you say something in a MUC - (through the /say command or by direct input). The difference with - *conversation_say* is just that *conversation_say_after* hook is called AFTER - the xhtm-im body has been generated and the message has been displayed on the - conversation, this means that if you modify the body, the message that will be - sent will not be the same that the one displayed in the text buffer. So you - *MUST* not insert any color attribute in the body using this hook. The hook is - less safe that *conversation_say* and most of the time you should not use it at - all. The parameters given to the handlers are: - -* _message_: Message to be sent. -* _tab_: Tab in which the message will be sent. - -*muc_msg*:: +message+, +tab+ + -The handlers for this event are called whenever you receive a message in a MUC. - The parameters given to the handler are: - -* _message_: Message received. -* _tab_: Tab in which the message was received. - -*private_msg*:: +message+, +tab+ + -The handlers for this event are called whenever you receive a message in a - private conversation in a MUC. The parameters given to the handler are: - -* _message_: Message received. -* _tab_: Tab in which the message was received. - -*conversation_msg*:: +message+, +tab+ + -The handlers for this event are called whenever you receive a message in a - direct conversation. The parameters given to the handler are: - -* _message_: Message received. -* _tab_: Tab in which the message was received. - -*normal_chatstate*:: +message+, +tab+ + -The handlers for this events are called whenever you receive a chatstate in a - direct conversation. The parameters given to this handler are: - -* _message_: Chatstate received. -* _tab_: Tab of the concerned conversation - -*muc_chatstate*:: +message+, +tab+ + -The handlers for this events are called whenever you receive a chatstate in a - MUC. The parameters given to this handler are: - -* _message_: Chatstate received. -* _tab_: Tab of the concerned MUC. - -*private_chatstate*:: +message+, +tab+ + -The handlers for this events are called whenever you receive a chatstate in a - private conversation in a MUC. The parameters given to this handler are: - -* _message_: Chatstate received. -* _tab_: Tab of the concerned conversation. - -*normal_presence*:: +presence+, +resource+ + -The handlers for this events are called whenever you receive a presence from - one of your contacts. The parameters given to this handler are: - -* _presence_: Presence received. -* _resource_: The resource that emitted the presence. - -*muc_presence*:: +presence+, +tab+ + -The handlers for this events are called whenever you receive a presence from - someone in a MUC. The parameters given to this handler are: - -* _presence_: Presence received. -* _tab_: Tab of the concerned MUC. - -*send_normal_presence*:: +presence+ + -The handlers for this events are called whenever you send a presence “normal” -presence, i.e. a presence for your contacts or some direct JIDs, but *not* in a -MUC. The parameters given to this handler are: - -* _presence_: The presence about to be sent. - - -The following can be deduced from the muc_presence event, but are more - specialized. - -*muc_join*:: +presence+, +tab+ + -The handlers for this event are called when someone joins a MUC (can be you). - -* _presence_: Presence received. -* _tab_: Tab of the concerned MUC. - -*muc_nickchange*:: +presence+, +tab+ + -The handlers for this event are called when someone changes his nick in a MUC. - -* _presence_: Presence received. -* _tab_: Tab of the concerned MUC. - -*muc_ban*:: +presence+, +tab+ + -The handlers for this event are called when someone gets banned in a MUC. - -* _presence_: Presence received. -* _tab_: Tab of the concerned MUC. - -*muc_kick*:: +presence+, +tab+ + -The handlers for this event are called when someone gets kicked in a MUC. - -* _presence_: Presence received. -* _tab_: Tab of the concerned MUC. - -*ignored_private*:: +message+ +tab+ + -The handlers for this event are called when a private message gets ignored. - -* _message_: Message received. -* _tab_: Tab of the concerned message. - -SleekXMPP events -~~~~~~~~~~~~~~~~ - -For the sleekxmpp events, please refer to the - https://github.com/fritzy/SleekXMPP/wiki/Event-Index[sleekxmpp event index]. - - -CAUTION: Plugins are in an experimental state and this API might change - slightly in a near future. You have to be aware of that while making a plugin. - -Examples --------- - -[[example-1]] -.Add a simple command that sends "Hello World!" into the conversation -================================================================= -[source,python] ---------------- -class Plugin(BasePlugin): - def init(self): - self.add_command('hello', self.command_hello, "Usage: /hello\nHello: Send 'Hello World!'", None) - - def command_hello(self, arg): - self.core.send_message('Hello World!') ---------------- -================================================================= - -[[example-2]] - -.Adds an event handler that sends ``tg'' to a groupchat when a message is received from someone named ``Partauch'' -===================================================================== -[source,python] ---------------- -class Plugin(BasePlugin): - def init(self): - self.add_event_handler('muc_msg', self.on_groupchat_message) - - def on_groupchat_message(self, message, tab): - if message['mucnick'] == "Partauche": - tab.command_say('tg') ---------------- -===================================================================== - diff --git a/doc/en/plugins/.translate.txt b/doc/en/plugins/.translate.txt deleted file mode 100644 index cb605699..00000000 --- a/doc/en/plugins/.translate.txt +++ /dev/null @@ -1,51 +0,0 @@ -Translate -========= - -This plugin translates what is said in the groupchats using google translate. - -Installation ------------- -You only have to load the plugin. - -================ - - /load translate - -================ - -Configuration -------------- - -You can set the rooms you want to be translated in the configuration file, -with their associated language. If no language is specified, the _default_ -option is used, and if no option is set, _en_ is used as a target language. - -.No default set -===================== -[source,conf] ------------- -[translate] -poezio@muc.poezio.eu = en ------------- -===================== - -.Default set -===================== -[source,conf] -------------- -[translate] -default = fr -prosody@conference.prosody.im = -jabberfr@chat.jabberfr.org = en -------------- -===================== - -You can of course also set the options with _/set_: - -============================ - - /set translate| default jp - - /set translate|translate poezio@muc.poezio.eu en - -============================ diff --git a/doc/en/plugins/admin.txt b/doc/en/plugins/admin.txt deleted file mode 100644 index c7755fac..00000000 --- a/doc/en/plugins/admin.txt +++ /dev/null @@ -1,34 +0,0 @@ -Admin aliases -============= - -This plugin adds several aliases, to shorten roles/affiliations management. - -Installation ------------- -You only have to load the plugin. - -================ - - /load admin - -================ - - -Aliases ------- - -Roles -~~~~~ -- _/visitor_ -- _/participant_ -- _/moderator_ -- _/mute_ (same as _/visitor_) -- _/op_ (same as _/moderator_) - -Affiliations -~~~~~~~~~~~~ -- _/admin_ -- _/member_ -- _/noaffiliation_ (sets the affiliation to _none_) -- _/owner_ -- _/voice_ (same as _/member_) diff --git a/doc/en/plugins/alias.txt b/doc/en/plugins/alias.txt deleted file mode 100644 index ee45ae63..00000000 --- a/doc/en/plugins/alias.txt +++ /dev/null @@ -1,77 +0,0 @@ -Aliases -======= - -Installation ------------- -You only have to load the plugin: - -============== - - /load alias - -============== - -Usage ------ - -This plugin defines two new global commands: _/alias_ and _/unalias_. - -alias -~~~~~~ -This command is used like this: - -=============== - - /alias my_alias an_existing_command fixed_arg - -================ -This will create a _/my_alias_ command, that when called, will run -_/an_existing_command fixed_arg_. If you give other parameters to the alias, -they will be passed to the existing command as well. - - -You can omit the _fixed_arg_ part if you don’t want to, of course. - - -There is also the possibility to change the order of parameters: - -================ -With - - /alias myalias command "%1 %0" - -The command: - - /myalias foo bar - -Will then run - - /command bar foo - -because the %1 parameter is placed before the %0. - -================ - -The numbers can be from 0 to 9. - -.Possible examples -=================== - - /alias truc say "%1 is AFTER %0 usually" - - /alias q quit - - /alias partauche ban "Partauche \"tg %0\"" - -=================== - -unalias -~~~~~~~~ - -This command removes a defined alias. - -================== - - /unalias defined_alias - -================= diff --git a/doc/en/plugins/amsg.txt b/doc/en/plugins/amsg.txt deleted file mode 100644 index afac32ea..00000000 --- a/doc/en/plugins/amsg.txt +++ /dev/null @@ -1,24 +0,0 @@ -Amsg -==== - -This plugin broadcasts a message to all your joined rooms. - -Installation ------------- -You only have to load the plugin. - -================ - - /load amsg - -================ - - -Command -------- - -=============== - - /amsg message - -============== diff --git a/doc/en/plugins/day_change.txt b/doc/en/plugins/day_change.txt deleted file mode 100644 index e9c8bf28..00000000 --- a/doc/en/plugins/day_change.txt +++ /dev/null @@ -1,15 +0,0 @@ -Day change -========== - -This plugin adds a message at 00:00 in each of your chat tabs saying that the -date has changed. - -Installation ------------- -You only have to load the plugin. - -================ - - /load day_change - -================ diff --git a/doc/en/plugins/display_corrections.txt b/doc/en/plugins/display_corrections.txt deleted file mode 100644 index dff55afe..00000000 --- a/doc/en/plugins/display_corrections.txt +++ /dev/null @@ -1,32 +0,0 @@ -Display corrections -=================== - -Lists old versions of a corrected message. - -Installation ------------- - -============================ - - /load display_corrections - -============================ - - -Usage ------ -This plugin adds a _/display_corrections_ command that will display a list of -old versions of a message. - - -_display_corrections_ without argument will list the last corrected message, -if any is found. If an integer argument is given, _display_corrections_ will -go back gradually in the buffer to list the previous corrected messages, and so -on. - - -If you are scrolling in the buffer, poezio will list the corrected messages -starting from the first you can see. (although there are some problems with -multiline messages). - - diff --git a/doc/en/plugins/exec.txt b/doc/en/plugins/exec.txt deleted file mode 100644 index 5ef1d49f..00000000 --- a/doc/en/plugins/exec.txt +++ /dev/null @@ -1,38 +0,0 @@ -Exec -==== - -This plugin lets you execute a system command through poezio. - -Installation ------------- - -You only have to load the plugin. - -================ - - /load exec - -================ - -Command -------- - -CAUTION: Running commands that start a daemon or an interface is not a good -idea. - -=============== - - /exec command - -Will give you the result in the information buffer. - - /exec -o command - -Will send the result of the command into the current tab, if possible. - - /exec -O command - -Will send the result of the command and the command summary into the current -tab, if possible. - -============== diff --git a/doc/en/plugins/figlet.txt b/doc/en/plugins/figlet.txt deleted file mode 100644 index ece28f11..00000000 --- a/doc/en/plugins/figlet.txt +++ /dev/null @@ -1,24 +0,0 @@ -Figlet -====== - -This plugin uses figlet to transform every message into a big ascii-art -message. - -Installation ------------- -You only have to load the plugin (and have _figlet_ installed, of course). - -================ - - /load figlet - -================ - - -Usage ------ - -Say something. - -NOTE: Can create fun things when used with link:rainbow.html[the rainbow -plugin]. diff --git a/doc/en/plugins/gpg.txt b/doc/en/plugins/gpg.txt deleted file mode 100644 index a39b68a4..00000000 --- a/doc/en/plugins/gpg.txt +++ /dev/null @@ -1,101 +0,0 @@ -GPG -=== - -This plugin implements the -link:http://xmpp.org/extensions/xep-0027.html[XEP-0027] “Current Jabber OpenPGP -Usage”. - -This is a plugin used to encrypt one-to-one conversation using the PGP -encryption method. You can use it if you want really good privacy. Without this -encryption, your messages are encrypted *at least* from your client (poezio) to -your server. The message is decrypted by your server and you cannot control the -encryption method of your messages from your server to your contact’s server -(unless you are your own server’s administrator), nor from your contact’s -server to your contact’s client. - -This plugin does end-to-end encryption. This means that *only* your contact can -decrypt your messages, and it is fully encrypted during *all* its travel -through the internet. - -Note that if you are having an encrypted conversation with a contact, you can -*not* send XHTML-IM messages to him. They will be remove and be replaced by -plain text messages. - -Installation and configuration ------------------------------- - -You should autoload this plugin, as it will send your signed presence directly -on login, making it easier for your contact’s clients to know that you are -supporting GPG encryption. To do that, use the _plugins_autoload_ configuration -option. - -You need to create a plugin configuration file. Create a file named _gpg.cfg_ -into your plugins configuration directory (_~/.config/poezio/plugins_ by -default), and fill it like this: - -[source,conf] ---------------------------------------------------------------------- -[gpg] -keyid = 091F9C78 -passphrase = your OPTIONAL passphrase - -[keys] -example@jabber.org = E3CFCDE2 -juliet@xmpp.org = EF27ABCD ---------------------------------------------------------------------- - -The *Poezio* section is about your key. You need to specify the keyid, for the -key you want to use. You can as well provide a passphrase. If you don’t, you -should use a gpg agent or something like that that will ask your passphrase -whenever you need it. - -The *keys* section contains your contact’s id keys. For each contact you want -to have encrypted conversations with, add her/his JID associated with the keyid -of his/her key. - -And that’s it, now you need to talk directly to the *full* jid of your -contacts. Poezio doesn’t let you encrypt messages whom recipients is a bare -JID. - -Additionnal information on GnuPG --------------------------------- - -Create a key -~~~~~~~~~~~~ - -To create a personal key, use -================== -gpg --gen-key -================== -and fill the instructions - - -Keyid -~~~~~ -The keyid (required in the gpg.cfg configuration file) is a 8 character-long -key. You can get the ones you created or imported by using the command -======================= -gpg --list-keys -======================= -You will get something like - ---------------------------------------------------------------------- -pub 4096R/01234567 2011-11-11 -uid Your Name Here (comment) -sub 4096R/AAFFBBCC 2011-11-11 - -pub 2048R/12345678 2011-11-12 [expire: 2011-11-22] -uid A contact’s name (comment) -sub 2048R/FFBBAACC 2011-11-12 [expire: 2011-11-22] ---------------------------------------------------------------------- - -In this example, the keyids are *01234567* and *12345678*. - -Share your key -~~~~~~~~~~~~~~ -Use -=========================== -gpg --send-keys --keyserver pgp.mit.edu -=========================== -to upload you public key on a public server. - diff --git a/doc/en/plugins/index.txt b/doc/en/plugins/index.txt deleted file mode 100644 index 1c009998..00000000 --- a/doc/en/plugins/index.txt +++ /dev/null @@ -1,155 +0,0 @@ -Poezio plugins -============== - -Starting from the 0.7.5 version, poezio supports plugins. -Here is a quick howto and a plugin index. - - -Setting up plugins ------------------- -Poezio seeks the plugins in the _~/.local/share/poezio/plugins/_ dir (more -generally, the _$XDG_DATA_HOME/poezio/plugins/_ dir), but that can be changed -by setting the _plugins_dir_ option in the -link:../configure.html[configuration file] to the directory where you want to -put your plugins. - -This means that if you want to use a plugin, you have to copy it (the .py file or the directory) into _plugins_dir_. - - -Plugins autostart ------------------ -Use the _plugins_autoload_ option (from the -link:../configure.html[configuration file]) to select which plugins should be -loaded on startup. The value is a list of plugin names separated by spaces, -e.g. - -.plugins_autoload example ---------- -plugins_autoload = "gpg tell exec" ---------- - -Plugins configuration ---------------------- -Most plugins will manage their configuration internally, and you do not (and -should not) have to edit it, but some (e.g. mpd_client or gpg) require manual -editing (the _/set_ command can be used, but it is not pleasant to set -multiple values with it). - -The plugin configuration directory is located in _~/.config/poezio/plugins/_ -(or _$XDG_CONFIG_HOME/poezio/plugins/_) and the file related to a specific -plugin is named _plugin_name.cfg_. The configuration options should usually be -inside a section named after the plugin (sections are delimited with _[]_). - -.section example --------------- -[plugin_name] -key = value -other_key = other_value --------------- - - -Plugins index -------------- - -[horizontal] -*Admin*:: link:admin.html[Room administration plugin] - - Creates convenient aliases for MUC administration. - -*Alias*:: link:alias.html[Custom aliases plugin] - - Allows you to create your own aliases. - -*Amsg*:: link:amsg.html[Message broadcast plugin] - - Allows a message to be broadcasted on all the rooms your arein. - Caution: do not overuse. - -*Day Change*:: link:day_change.html[Day change plugin] - - Logs the day change inside the buffers, to keep track of the days when - backlogging. - -*Display corrections*:: link:display_corrections.html[Display corrections -plugin] - - Lists old versions of a corrected message. - -*Exec*:: link:exec.html[System command plugin] - - Runs a system command an optionally sends the output as a message. - -*Figlet*:: link:figlet.html[Figlet plugin] - - Ascii-art writing (requires the _figlet_ package on your system). - -*GPG*:: link:gpg.html[GnuPG plugin] - - Allows encrypted exchanges and presence signing using GnuPG. - -*IQ Show*:: IQ showing plugin - - Shows the received IQs, for debugging purposes. - -*Link*:: link:link.html[Link opener plugin] - - Opens links in a web browser, locally or remotely using a FIFO and SSH. - -*MPD Client*:: link:mpd_client.html[MPD client plugin] - - Sends the current song (and optionally the progress inside the song) to - the current (chat) tab. - -*OTR*:: link:otr.html[Off-The-Record plugin] - - Allows encrypted and deniable exchanges using OTR. - -*PacoKick*:: link:pacokick.html[Random kick plugin] - - Kicks a random user in the room. - -*Ping*:: link:ping.html[XMPP Ping plugin] - - Sends a ping probe to an entity (XEP-0199) - -*Quote*:: link:quote.html[Quoting plugin] - - Adds a /quote command to quote a message at HH:MM:SS and put it in the - input (to prevent painful copy/pastes). - -*Rainbow*:: link:rainbow.html[Rainbow plugin] - - Sends your messages in rainbow colors using XHTML-IM. - -*Reminder*:: link:reminder.html[Reminder plugin] - - Reminds you to do something every now and then. - -*Screen Detach*:: link:screen_detach.html[Screen status plugin] - - Changes your status to _away_ if the screen poezio is in is detached. - -*Simple notify*:: link:simple_notify.html[Simple notification plugin] - - Sends a notification with a command of your choice on (non-MUC) messages. - -*Status*:: link:status.html[Status aliases plugin] - - Adds convenient aliases to /status (/away, etc). - -*Tell*:: link:tell.html[Automated delayed messages plugin] - - Tells a message to a nick when he connects to a MUC. - -*Uptime*:: link:uptime.html[Uptime plugin] - - Gets the uptime of a XMPP server or a component. - -*Replace*:: link:replace.html[Replace plugin] - - Replace some patterns in your messages. - -*Time Marker*:: link:time_marker.html[Time marker plugin] - - Display the time between two messages. - diff --git a/doc/en/plugins/link.txt b/doc/en/plugins/link.txt deleted file mode 100644 index 830a206b..00000000 --- a/doc/en/plugins/link.txt +++ /dev/null @@ -1,71 +0,0 @@ -Link -==== - -Opens links in a browser. - -Installation ------------- - -First use case: local use -~~~~~~~~~~~~~~~~~~~~~~~~~ -If you use poezio on your workstation, this is for you. -You only have to load the plugin: - -============== - - /load link - -============== - -Second use case: remote use -~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you use poezio through SSH, this is for you. - -NOTE: Small explanation: Poezio will create a -https://en.wikipedia.org/wiki/Named_pipe[Unix FIFO] and send the commands in, -and you will have to run a dæmon locally with ssh, to get those commands. - -First, set the _exec_remote_ option in the config file to _true_. Then select -the directory you want to put the fifo in (default is the current - directory, _./_), the _poezio.fifo_ file will be created there. - -After that, load the plugin: - -============ - - /load link - -============ - -And open a link with _/link_ (as described below), this will create the FIFO. - -You need to grab poezio’s sources on your client computer, or at least the -http://gitweb.louiz.org/?p=poezio;a=blob_plain;f=src/daemon.py;hb=HEAD[daemon.py] -file. - -Finally, on your client computer, run the ssh command: - -============ - - ssh toto@example.org "cat ~/poezio/poezio.fifo" | python3 daemon.py - -=========== - - -Usage ------ -This plugin adds a _/link_ command that will open the links in _firefox_. If -you want to use another browser, you can use the _/set_ command to change the -_browser_ option in the config file. - - -_/link_ without argument will open the last received link, if any is found. -If an integer argument is given, /link will go back gradually in the buffer -to open the previous link, and so on. - - -If you are scrolling in the buffer, poezio will open the links starting from -the first you can see. (although there are some problems with multiline -messages). - - diff --git a/doc/en/plugins/mpd_client.txt b/doc/en/plugins/mpd_client.txt deleted file mode 100644 index c657e314..00000000 --- a/doc/en/plugins/mpd_client.txt +++ /dev/null @@ -1,55 +0,0 @@ -MPD Client -========== - -This plugin is here to display what you are listening to in a chat tab. - - -Installation and configuration ------------------------------- - -Installation -~~~~~~~~~~~~ - -You need https://github.com/Mic92/python-mpd2[python-mpd], in its python3 -version. - -Then you can load the plugin. - -============== - - /load mpd_client - -============== - -Configuration -~~~~~~~~~~~~~ - -You have to put the following into _mpd_client.cfg_, as explained in -link:index.html[the index page]. - -NOTE: If you do not put anything, the plugin will try to connect to -_localhost:6600_ with no password. - -[source,conf] ---------------------------------------------------------------------- -[mpd_client] -host = the_mpd_host -port = 6600 -password = password if necessary ---------------------------------------------------------------------- - - -Usage ------ - -======= - - /mpd - -Will show the current song, artist, and album - - /mpd full - -Will show the current song, artist, and album, plus a nice progress bar. - -====== diff --git a/doc/en/plugins/otr.txt b/doc/en/plugins/otr.txt deleted file mode 100644 index 533f6b4b..00000000 --- a/doc/en/plugins/otr.txt +++ /dev/null @@ -1,113 +0,0 @@ -OTR -=== - -*DISCLAIMER: THE OTR LIB IS IN AN EXPERIMENTAL STATE AND SHOULD NOT BE -CONSIDERED AS ENTIRELY RELIABLE* - -('though it works pretty well') - -This plugin implements http://wiki.xmpp.org/web/OTR[Off The Record messaging]. - -This is a plugin used to encrypt one-to-one conversation using the OTR -encryption method. You can use it if you want good privacy, deniability, -authentication, and strong secrecy. Without this -encryption, your messages are encrypted *at least* from your client (poezio) to -your server. The message is decrypted by your server and you cannot control the -encryption method of your messages from your server to your contact’s server -(unless you are your own server’s administrator), nor from your contact’s -server to your contact’s client. - -This plugin does end-to-end encryption. This means that *only* your contact can -decrypt your messages, and it is fully encrypted during *all* its travel -through the internet. - -Note that if you are having an encrypted conversation with a contact, you can -*not* send XHTML-IM messages to him. They will be removed and be replaced by -plain text messages. - -Installation and configuration ------------------------------- - -To use the OTR plugin, you must first install libopenotr. - -If you use Archlinux, there is a https://aur.archlinux.org/packages.php?ID=57957[libopenotr-git] package on the AUR. - -If not, then you will have to install it by hand. - -First, clone the repo and go inside the created directory: - -============================================== -[source,bash] -------------- -git clone https://github.com/teisenbe/libopenotr.git - -cd libopenotr -------------- -============================================== - -then run autogen.sh and configure - -============ -[source,bash] -------------- -sh autogen.sh - -./configure --enable-gaping-security-hole -------------- -============ - -Then compile & install the lib: - -============ -[source,bash] -------------- -make - -sudo make install -------------- -============ - -Finally, install the python module: - -============================= -[source,bash] -------------- -python3 setup.py build - -sudo python3 setup.py install -------------- -============================= - - - -Usage ------ - -To use OTR, make sure the plugin is loaded (if not, then do /load otr). - -Once you are in a private conversation, you have to do a: - -========== - - /otr start - -========== - -The status of the OTR encryption should appear in the bar between the chat and -the input "OTR: encrypted". - - -Once you’re done, end the OTR session with - -========== - - /otr end - -========== - - -Known problems --------------- - - -Empty messages send when changing status. diff --git a/doc/en/plugins/pacokick.txt b/doc/en/plugins/pacokick.txt deleted file mode 100644 index a3a1b851..00000000 --- a/doc/en/plugins/pacokick.txt +++ /dev/null @@ -1,27 +0,0 @@ -PacoKick -======== - -This plugin adds a _/pacokick_ command, which is a random kick. - -Installation ------------- -You only have to load the plugin. - -================ - - /load pacokick - -================ - -Usage ------ - -If you are a moderator in a room, do - -============= - - /pacokick - -============ - -to kick someone randomly. diff --git a/doc/en/plugins/ping.txt b/doc/en/plugins/ping.txt deleted file mode 100644 index b19ca314..00000000 --- a/doc/en/plugins/ping.txt +++ /dev/null @@ -1,26 +0,0 @@ -Ping -==== - -This plugin allows you to ping an entity. - -Installation ------------- -You only have to load the plugin. - -================ - - /load ping - -================ - - -Command -------- - -Globally, you can do _/ping jid@example.com_ to get a ping. - -In a MUC, you can either do it to a JID or a nick (_/ping nick_ or _/ping -jid@example.com_). - -In a private or a direct conversation, you can do _/ping_ to ping the current -interlocutor. diff --git a/doc/en/plugins/quote.txt b/doc/en/plugins/quote.txt deleted file mode 100644 index 526e3aa7..00000000 --- a/doc/en/plugins/quote.txt +++ /dev/null @@ -1,35 +0,0 @@ -Quote -===== - -This plugin allows you to quote messages easily. - -Installation ------------- -You only have to load the plugin. - -================ - - /load quote - -================ - -Usage -------- - -=============== - - /quote - -============== - -Timestamp is HH:MM:SS, and can be completed with [tab]. - -.Command example -========== - - /quote 21:12:23 - -========= - -If there is a message at 21:12:23, it will be put in the input. If there -isn’t, you will get a warning. diff --git a/doc/en/plugins/rainbow.txt b/doc/en/plugins/rainbow.txt deleted file mode 100644 index 5c72b149..00000000 --- a/doc/en/plugins/rainbow.txt +++ /dev/null @@ -1,22 +0,0 @@ -Rainbow -======= - -This plugin colors each character of a message with a random color. - -Installation ------------- -You only have to load the plugin. - -================ - - /load rainbow - -================ - - -Usage ------ - -Say something. - -NOTE: Can create fun things when used with link:figlet.html[the figlet plugin]. diff --git a/doc/en/plugins/reminder.txt b/doc/en/plugins/reminder.txt deleted file mode 100644 index 5fec9bd0..00000000 --- a/doc/en/plugins/reminder.txt +++ /dev/null @@ -1,76 +0,0 @@ -Reminder -======== - -Installation ------------- -You only have to load the plugin: - -============== - - /load reminder - -============== - -Usage ------ -This plugin defines three new global commands: _/remind_, _/done_, and -_/tasks_. - -remind -~~~~~~ -================ - - /remind