diff options
| author | mathieui <mathieui@mathieui.net> | 2013-04-08 18:52:35 +0200 |
|---|---|---|
| committer | mathieui <mathieui@mathieui.net> | 2013-04-08 18:52:35 +0200 |
| commit | bd8d38d711e15d42ac8e797723af5242e4c3f4fb (patch) | |
| tree | d3ea6da641be1c7e67a3123071cb816933436502 | |
| parent | e5f219d43edbb4b05c8890f81f2f93b90e215a10 (diff) | |
| download | poezio-bd8d38d711e15d42ac8e797723af5242e4c3f4fb.tar.gz poezio-bd8d38d711e15d42ac8e797723af5242e4c3f4fb.tar.bz2 poezio-bd8d38d711e15d42ac8e797723af5242e4c3f4fb.tar.xz poezio-bd8d38d711e15d42ac8e797723af5242e4c3f4fb.zip | |
Beginning of the migration to reST documentation
68 files changed, 1175 insertions, 3878 deletions
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 <target>' where <target> 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 <server>). - -*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 -<server>). - -*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 <<add-command,add_command>>, and initialize -everything to make your plugin actually do something. <<example-1,ex 1>>, - <<example-2,ex 2>> - -*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. <<example-1,ex 1>> - -* _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. <<example-2,ex 2>> - -* _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 -<<events-list,all available events>>. -* _handler_: The method that will be called whenever the event occurs. -It must accept the arguments specified for that event in the - <<events-list,events list>>. -* _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) <email@example.org> -sub 4096R/AAFFBBCC 2011-11-11 - -pub 2048R/12345678 2011-11-12 [expire: 2011-11-22] -uid A contact’s name (comment) <fake@fake.fr> -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 <keyid> -=========================== -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> - -============== - -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 <time> <todo> - -================ - -Will remind you to do _<todo>_ every _<time>_. - - -.Time in seconds -================ - - /remind 600 Work! - -Will remind you to work every 10 minutes - -================ - -Defining the time in seconds is not really usable, so you can describe it -with days, hours, and minutes, e.g: - -.Time in a string -======================= - - /remind 1h23m "Get up" - -Will remind you to get up every 1 hour 23 minutes - -======================= - - -done -~~~~ - -Removes a reminder. - -============ - - /done <id> - -=========== - -The _id_ is found using _/tasks_. - -tasks -~~~~~ - -=============== - - /tasks - -================ - -Will print a list of the tasks, their ids, and their frequency, into the -information buffer. - diff --git a/doc/en/plugins/replace.txt b/doc/en/plugins/replace.txt deleted file mode 100644 index 3a17ff20..00000000 --- a/doc/en/plugins/replace.txt +++ /dev/null @@ -1,71 +0,0 @@ -Replace -======= - -Replace some patterns in a message before sending it. - - -Installation ------------- -You only have to load the plugin. - -============== - - /load replace - -============== - -Usage ------ -Insert a pattern in the form - -========= - -%pattern% - -========= - -in your message, and it will be replaced by the corresponding text. - -The list of provided patterns is: - -- _time_: Insert the current time -- _date_: Insert the current date -- _datetime_: Insert the current date and time -- _random_nick_: Insert a random nick from the current MUC -- _dice_: Insert a random number between 1 and 6 - - -Add your own pattern --------------------- - -You can easily edit this plugin to add your own patterns. For example if -don’t want to search for an insult everytime you’re angry, you can create a -curse pattern this way: - -- In the init(self) method of the Plugin class, add something like - -================ -[source,python] - self.patterns['curse'] = replace_curse -================ - -- then define a function (not a method of the Plugin class) at the bottom -of the file. For example: - - -========================================================== -[source,python] -def replace_curse(message, tab): - return random.choice(['dumb shit', 'idiot', 'moron']) -========================================================== - -and you can now use something like - -==================== -Shut up, %curse%! -==================== - -in your everyday-conversations. - -For more conveniance, you can read your nice words from a file, do whatever -you want in that function, as long as it returns a string. diff --git a/doc/en/plugins/screen_detach.txt b/doc/en/plugins/screen_detach.txt deleted file mode 100644 index 3277ae4d..00000000 --- a/doc/en/plugins/screen_detach.txt +++ /dev/null @@ -1,15 +0,0 @@ -Screen detach -============= - -This plugin will set your status to _away_ if you detach your screen. - -Installation ------------- -You only have to load the plugin. - -================ - - /load screen_detach - -================ - diff --git a/doc/en/plugins/send_delayed.txt b/doc/en/plugins/send_delayed.txt deleted file mode 100644 index 02321441..00000000 --- a/doc/en/plugins/send_delayed.txt +++ /dev/null @@ -1,34 +0,0 @@ -Send delayed -============ - -This plugin sends a message after a given time. - -Installation ------------- -You only have to load the plugin: - -============== - - /load send_delayed - -============== - -Usage ------ -This plugin defines one new command for chat tabs: _/send_delayed_. - -================ - - /send_delayed <delay> <message> - -================ - -_delay_ can be seconds, or a time-string (as in the -link:reminder.html[reminder plugin]). - -.Time in a string -======================= - - /send_delayed 5h "Hey, did you know that it’s 6AM and I’m sleeping?" - -======================= diff --git a/doc/en/plugins/simple_notify.txt b/doc/en/plugins/simple_notify.txt deleted file mode 100644 index b12e7525..00000000 --- a/doc/en/plugins/simple_notify.txt +++ /dev/null @@ -1,47 +0,0 @@ -Simple Notify -============= - -This plugin lets you execute a command, to notify you from new important -messages. - -Installation and configuration ------------------------------- - -You need to create a plugin configuration file. Create a file named _simple_notify.cfg_ -into your plugins configuration directory (_~/.config/poezio/plugins_ by -default), and fill it like this: - -[source,conf] ---------------------------------------------------------------------- -[simple_notify] -command = notify-send -i /path/to/poezio/data/poezio_80.png "New message from %(from)s" "%(body)s" ---------------------------------------------------------------------- - -[source,conf] ---------------------------------------------------------------------- -[simple_notify] -command = echo \\<%{from}s\\> %{body}s >> some.fifo -delay = 3 -after_command = echo >> some.fifo ---------------------------------------------------------------------- - -You can put any command, instead of these ones. You can also use the -special keywords _%(from)s_ and _%(body)s_ that will be replaced -directly in the command line by the author of the message, and the body. - -The first example shown above will display something like this: -image:../../images/simple_notify_example.png["Simple notify example", -title="Simple notify example"] - -The second example will first write the author and the message in a -fifo, that fifo can locally be read by some other program (was tested -with the xmobar PipeReader command, which displays what is read from a -fifo into a status bar. Be careful, you have two different fifos in -that case, don’t get confused). The delay and command_after options -are used to erase/delete/kill the notification after a certain -delay. In our example it is used to display an empty message in our -xmobar, erasing the notification after 3 seconds. - -NOTE: If you set the _exec_remote_ option to _true_ into the -link:../configure.html[main configuration file], the command will be executed -remotely (as explained in the link:link.html[/link help]). diff --git a/doc/en/plugins/status.txt b/doc/en/plugins/status.txt deleted file mode 100644 index 63568a71..00000000 --- a/doc/en/plugins/status.txt +++ /dev/null @@ -1,25 +0,0 @@ -Status aliases -============== - -This plugin adds several aliases, to shorten status changes. - -Installation ------------- -You only have to load the plugin. - -================ - - /load status - -================ - -Aliases ------- - -- _/afk_ (same as _/away_) -- _/available_ -- _/away_ -- _/dnd_ -- _/busy_ -- _/chat_ -- _/xa_ diff --git a/doc/en/plugins/tell.txt b/doc/en/plugins/tell.txt deleted file mode 100644 index 5bcda499..00000000 --- a/doc/en/plugins/tell.txt +++ /dev/null @@ -1,40 +0,0 @@ -Tell -==== - -This plugin sends a message to someone when he next joins. - -Installation ------------- -You only have to load the plugin: - -============== - - /load tell - -============== - -Usage ------ -This plugin defines two new commands for MUC tabs: _/tell_ and _/untell_. - -tell -~~~~ - -================ - - /tell <nick> <message> - -================ - - -untell -~~~~~~ - -============== - - /untell <nick> - -============= - -Will remove all the messages poezio should have sent to _<nick>_ on his next -join. diff --git a/doc/en/plugins/time_marker.txt b/doc/en/plugins/time_marker.txt deleted file mode 100644 index ad171b0d..00000000 --- a/doc/en/plugins/time_marker.txt +++ /dev/null @@ -1,31 +0,0 @@ -Time Marker -=========== - -Display the time between two messages. - -Installation ------------- - -You only have to load the plugin. - -================ - - /load amsg - -================ - -Configuration -------------- - -You can configure the minimum delay between two messages, to display the time marker, in seconds. The default is 10 minutes (aka 600 seconds). - -[source,conf] ---------------------------------------------------------------------- -[time_marker] -delay = 600 ---------------------------------------------------------------------- - -Usage ------ - -Messages like “2 hours, 25 minutes passed…” are automatically displayed into the converstation. You don’t need to (and can’t) do anything. diff --git a/doc/en/plugins/uptime.txt b/doc/en/plugins/uptime.txt deleted file mode 100644 index 95c8ad10..00000000 --- a/doc/en/plugins/uptime.txt +++ /dev/null @@ -1,35 +0,0 @@ -Uptime -====== - -This plugin retrieves the uptime of a server. - -Installation ------------- -You only have to load the plugin. - -================ - - /load uptime - -================ - - -Command -------- - -=============== - - /uptime <jid> - -============== - -Will retrieve the uptime of the server of _<jid>_. - -.Example usage -============== - - /uptime example.com - -21:54:45 Info> Server example.com online since 1d6h31m42s - -============= diff --git a/doc/en/ssl.txt b/doc/en/ssl.txt deleted file mode 100644 index ef7af349..00000000 --- a/doc/en/ssl.txt +++ /dev/null @@ -1,62 +0,0 @@ -SSL Management -============== - -Starting from version 0.7.5, poezio offers some options to check the validity -of a X.509 certificate. - -TOFU ----- - -The default handling method is the -link:https://en.wikipedia.org/wiki/User:Dotdotike/Trust_Upon_First_Use[TOFU/TUFU] -method. At your first connection, poezio will save the hash of the certificate -received, and will compare the received one and the first one for the next -connections. - - -If you are paranoid (or run poezio for the first time in an unsafe -environment), you can set the _certificate_ value of your config file yourself -(the hash, not colon-separated). - - -If the certificate is not the same, poezio will show an error message and wait -for confirmation: - -image:../images/ssl_warning.png["Warning message", title="Warning message"] - -If you press y, the change is validated an poezio will match the next certs -with the accepted one. - -If you press n, you will get the confirmation that the change has been -refused, and you will be disconnected. - -CA-Based --------- - -If you are connecting to a large server that has several front-facing -endpoints, you might be bothered by having to validate the change each time, -and you may want to check only if it the same authority delivered the -certificate. - -You can then set the _ca_cert_path_ option to the path of a file containing -the validation chain in link:https://tools.ietf.org/html/rfc1422.html[PEM -format] ; those certificates are usually in /usr/share/ca-certificates/ but it -may vary depending of your distribution. - -If the authority does not match when connecting, you should be disconnected. - -None ----- - -If you do not want to bother with certificate validation at all (which can be -the case when you run poezio on the same computer as your jabber server), you -can set the _ignore_certificate_ value to true, and let the _ca_cert_path_ -option empty (or even remove it). - - - - - - - - diff --git a/doc/en/themes.txt b/doc/en/themes.txt deleted file mode 100644 index c9e847cd..00000000 --- a/doc/en/themes.txt +++ /dev/null @@ -1,96 +0,0 @@ -Themes -====== - -This page describes how themes work in poezio and how to create or -modify one. - -A theme contains color attributes and character definitions. Poezio can display -up to _256_ colors if your terminal supports it. Most of the time, -if it doesn’t work, that’s because the _$TERM_ environnment variable is -wrong. For example with tmux or screen, set it to _screen-256color_, in -_xterm_, set it to _xterm-256color_, etc. If your terminal doesn’t have 256, -only 8 colors will be available, and poezio will replace the colors by one -of the 8 values available. Thus, some theme files may not work properly -if you only have 8 colors for example light gray on dark gray may -be converted to black on black if only 8 colors are available, making -the text impossible to read). The default theme should work properly in any -case. If not, that’s a bug. - -A theme file is a python file (with the .py extension) containing a -class, inheriting the *theming.Theme* class defined into the *theming* -poezio module. - -Create a theme --------------- - -To create a theme named foo, create a file named foo.py into the theme -directory (by default it’s _~/.local/share/poezio/themes/_) and insert -into it: - -[source,python] ----- -import theming - -class FooTheme(theming.Theme): - # Define here colors for that theme -theme = FooTheme() ----- - -To define a _color pair_ and assign it to the COLOR_NAME option, just do -[source,python] ----- -class FooTheme(theming.Theme): - COLOR_NAME = (fg_color, bg_color, opt_attr) ----- - -You do not have to define all the <<available-options,available options>>, -you can decide that your theme will only change some options, the other -one will just have the default value (from the default theme). - -Colors and attributes -~~~~~~~~~~~~~~~~~~~~~ -A color pair defines how the text will be displayed on the screen. It -has a _foreground color_ (fg_color), a _background color_ (bg_color) -and an *_optional_* _attribute_ (opt_attr). - -Colors -^^^^^^ -A color is a number between -1 and 255. If it -1, this is the default -color defined by your terminal (for example if your terminal displays -text white on black by default, a fg_color of -1 is white, and a bg_color -of -1 is black). If it’s between 0 and 256 it represents one of the colors -on the image: - -image::../images/theme_256_colors.png["The list of all 256 colors", title="The list of all 256 colors"] - -Attributes -^^^^^^^^^^ -An attribute is a python string (so, it has to be surrounded by -*" "* or *' '*). It can be one of the following - -* *'b'*: bold text -* *'u'*: underlined text - -Use a theme ------------ -To use a theme, just define the _theme_ option into the -link:configure.html[configuration file] to the name of the theme you want -to use. If that theme is not found, the default theme will be used instead. -Note that the default theme is defined directly into poezio’s source code, -and not in a theme file. - -Change the theme directory --------------------------- -To change the default theme directory (_~/.local/share/poezio/themes/_ by -default), you have to change the _themes_dir_ option in the -link:configure.html[configuration file] to the directory that contains your -theme files. - -[[available-options]] -Available options ------------------ - -CAUTION: This section is not complete. - -All available options can be found into the default theme, which is into the -_theming.py_ file from the poezio’s source code. diff --git a/doc/en/usage.txt b/doc/en/usage.txt deleted file mode 100644 index 273ca475..00000000 --- a/doc/en/usage.txt +++ /dev/null @@ -1,475 +0,0 @@ -Usage -===== - -This page is the main page of the documentation for poezio, explaining how to - use it and describing its interfaces. - -Poezio is composed of tabs which can be of various types. Each tab type has -a distinct interface, list of commands and list of key shortcuts, in addition -to the global commands and key shortcuts. - -Tabs ----- - -The Tab list -~~~~~~~~~~~~ - -Since Poezio 0.7.5, there are now two ways to show the available tabs: - -*The old way: horizontal list* - -On all tabs, you get a line showing the the list of all opened tabs. Each tab - has a number, each time you open a new tab, it gets the next available number. - -image:../images/tab_bar.png[title="Example of 5 opened tabs"] - -*The new way: vertical list* - -On all tabs, you get a pane on the left side of the screen that shows a list -of the opened tabs. As stated above, each tab has a number, and each time you -open a new tab, it gets the next available tab. - -image:../images/vert_tabs.png[title="Example of the vertical tab bar"] - - -This mode is enabled by putting the -link:configure.html[enable_vertical_tab_list] option to _true_ in the -configuration file. - -*Options for the tab list* - -See the link:configure.html[Configuration page] for the description of the -options. - -- _enable_vertical_tab_list_ -- _vertical_tab_list_size_ -- _vertical_tab_list_sort_ -- _show_tab_names_ -- _show_tab_numbers_ -- _show_inactive_tabs_ -- _use_tab_nicks_ - -Generalities -~~~~~~~~~~~~ -The tab numbered _0_ is always the _roster_ tab, the other tabs can be of any -type. - - -The status of a tab is represented by its color: - -* *[navy]#blue#* (tab _0_): an inactive tab of any type, nothing new to see - there. -* *[purple]#purple#* (tab _1_): a MultiUserChat tab with at least one new - unread message. -* *[green]#green#* (tab _2_): a tab of a private conversation with a new - message to read. -* *[teal]#cyan#* (tab _3_): the current tab. -* *[red]#red#* (tab _4_): a MultiUserChat tab with at least one new hightlight - message. - -You can go from one tab to another in many ways: - -* Ctrl+n and Ctrl+p -* <<command-win, win>> command -* <<command-next, next>> and <<command-prev, prev>> commands -* Alt+ a number -* Alt+j followed by a two-digits number -* Alt+e, this will jump to the next tab with the highest priority. Priority - applies in this order: private message > highlight message > normal message. - -Roster tab -~~~~~~~~~~ -This is a unique tab, always numbered _0_. It contains the list of your -contacts. You can add/remove/edit/search contacts from there, and you can open -a conversation with one of them. - -Use the _arrows_ to browse the list, the _space_ key to fold or unfold a group -or a contact. - -image:../images/roster.png["The roster tab", title="The roster tab"] - -* _1_: The area where information messages are displayed. -* _2_: The actual list of contacts. The first level is group, the second is the -* contacts and the third is the resources of you online contacts. -* _3_: More informations about the selected contact. - -MultiUserChat tab -~~~~~~~~~~~~~~~~~ - -This tab contains a multi-users conversation. - -image:../images/muc.png["The MUC tab", title="The MUC tab"] - -* _1_: The conversation window, this is where all the messages and events - related to the muc will be displayed. It can be scrolled up and down with - PageUp and PageDown. -* _2_: The participant list. Participants are listed by their role first, and - then alphabetically. - The status of each participant is symbolized using the _color_ of the - character on the left of its nick. - That character also shows the chatstate of each participant: - - _|_: inactive - - _X_: composing - - _A_: active - - _p_: paused + - + - The roles and affiliations of the participants are symbolized by the char - before the nick and its color. - The characters define the affiliations, and they mean: - - _~_: Owner - - _&_: Admin - - _+_: Member - - _-_: None + - + - And their color define their roles, and they mean: - - [red]#Red# : moderator - - [blue]#Blue#: participant - - [gray]#Grey#: visitor + - + - The nicks have a random color given by poezio. -* _3_: Your information in that MUC (the name of the room, your nick, your role - and affiliation). -* _4_: The topic of the room. - -You can configure the room (if you have the rights to do it) using the -_/configure_ command, open a private conversation with someone using the -_/query_ command, change or view the topic using the _/topic_ command… - -Private tab -~~~~~~~~~~~ -This is the tab opened with the _/query_ command, letting you talk in private -with a participant of a multi-users chat. - -image:../images/private.png["The private tab", title="The private tab"] - -This is just a simple one to one conversation, with a line showing the status, -name and chatstate of the participant. - -Conversation tab -~~~~~~~~~~~~~~~~ -A tab opened from the roster, to talk in private with one of your contacts. - -image:../images/conversation.png["The conversation tab", title="The conversation tab"] - -This is also just a simple one to one conversation, with a line showing the status, -name and chatstate of the participant, as well as a line at the top showing the -status message of the contact. - -Dataforms tab -~~~~~~~~~~~~~ - -This tab lets you view a form receive from a remote entity, edit the values and -send everything back. It is mostly used to configure MUCs with the _/configure_ -command but can actually be used for almost anything. - -image:../images/data_forms.png["The dataform tab", title="The dataform tab"] - -Use the _up_ and _down_ keys to go from one field to the other, and edit the -value using the _space_, _left_ or _right_ keys, or by entering text. - -You can then send the completed form using _Ctrl+y_ or cancel using _Ctrl+g_. - -List tab -~~~~~~~~ - -This tab lists all public rooms on a MUC service. It is currently very limited -but will be improved in the future. There currently is no way to search a room -or even to sort them. - -image:../images/list.png["The list tab", title="The list tab"] - -Use the _up_ and _down_ or _PageUp_ and _PageDown_ keys to browse the list, and -use _Enter_ or _j_ to join the selected room. - -You can sort the rooms by moving the direction arrows (_←_ or _→_)and pressing -_space_ when you are on the appropriate column. - -Commands --------- - -Commands start with the _/_ character and can take a list of any number -of arguments, separated by spaces. If an argument should contain a space, -you can use the _"_ character to surround this argument. - -The commands described in this page are shown like this: - -=========================================================== -/command <mandatory argument> [optional argument] -=========================================================== - -You can get the same help as below with the _/help_ command. - -NOTE: Use command parameters like this: - -* Do not use quotes if they are unnecessary (words without special chars or - spaces) -* If the command takes several agrguments, you need to put quotes around - arguments containing special chars such as backslashes or quotes -* If the command always takes only one argument, then do not use quotes even - for words containing special chars - -Global commands -~~~~~~~~~~~~~~~ - -These commands work in *any* tab. - -*/help [command]*:: If called without an argument, this command will list the - available commands. If it has a valid command as an argument, this command - will show the usage and the help for the given command. - -*/join [room_name][@server][/nick] [password]*:: Join the specified room. You - can specify a nickname after a slash (/). If no nickname is specified, you - will use the default_nick in the configuration file. You can omit the room - name: you will then join the room you're looking at (useful if you were - kicked). You can also provide a room_name without specifying a server, the - server of the room you're currently in will be used. You can also provide a - password to join the room. - -- Examples: -* /join room@server.tld -* /join room@server.tld/John -* /join room2 -* /join /me_again -* /join -* /join room@server.tld/my_nick password -* /join / password - -*/exit*:: Just disconnect from the server and exit poezio. - -*/quit*:: Like /exit. - -[[command-next]] -*/next*:: Go to the next room. - -[[command-prev]] -*/prev*:: Go to the previous room. - -[[command-win]] -*/win <number>*:: Go to the specified room. - -*/w <number>*:: Like /win. - -*/status <availability> [status message]*:: Set your availability and - (optionaly) your status message. The <availability> argument is one of - "available, chat, away, afk, dnd, busy, xa" and the optional [status] argument - will be your status message.' - -*/bookmark [roomname][/nick] [autojoin] [password]*:: Bookmark the specified - room. This command uses almost the same syntax as /join. Type /help join for - syntax examples. Note that when typing /bookmark on its own, the room will be - bookmarked with the nickname you're currently using in this room (instead of - default_nick). You can specify an optional *autojoin* and *password* if you - call it with the full line (/bookmark alone will put the room in autojoin - without password). The bookmarks stored with this command are stored on your - xmpp server. - -*/bookmark_local [roomname][/nick]*:: Bookmark the specified room (you will - then auto-join it on each poezio start). This commands uses almost the same - syntax as /join. Type /help join for syntax examples. Note that when typing - /bookmark on its own, the room will be bookmarked with the nickname you're - currently using in this room (instead of default_nick). The bookmarks stored - with this command will be stored locally. They have priority over the ones - stored online. - -*/remove_bookmark [room_jid]*:: Remove the bookmark on _room_jid_ or the one on - the current tab, if any. - -*/bookmarks*:: Show the current bookmarks. - -*/set [plugin|][section] <option> <value>*:: Set the value to the option in - your configuration file. You can, for example, change your default nickname - by doing "/set default_nick toto" or your resource with "/set resource - blabla". Doing so will write in the main config file, and in the main - section ([Poezio]). But you can also write to another section, with "/set - bindings M-i ^i", to a plugin configuration with "/set mpd_client| host - main" (notice the *|*, it is mandatory to write in a plugin), or even to - another section in a plugin configuration "/set plugin|other_section option - value". *toggle* can be used as a special value for a boolean option. It - just set the option to true if it’s currently false, and to false if it’s - currently true. - -*/move_tab <source> <destination>*:: Move tab <source> to <destination>. If -the create_gaps option is true, then it will leave a gap at the <source> -position, leading to usual behaviour. If create_gaps is not enabled, then the -tabs will number from 0 to your actual tab number, without gaps (which means -their number will change if you close a tab on the left of the list). - -*/theme [theme_name]*:: Reload the theme defined in the config file. If - _theme_name_ is given, this command will act like /set theme theme_name then - /theme. - -*/presence <jid> [type] [status]*:: Send a directed presence to _jid_ using - _type_ and _status_ if provided. - -*/rawxml <stanza>*:: Send a custom XML stanza. - -*/list [server.tld]*:: Get the list of public chatrooms in the specified server -. - -*/message <jid> [optional message]*:: Open a conversation with the specified - JID (event if it is not in our roster), and send a message to him, if - specified. - -*/version <jid>*:: Get the software version of the given JID (usually its XMPP - client and Operating System). - -*/invite <jid> <room> [reason]*:: Invite _jid_ to _room_ wit _reason_ (if - provided). - -*/invitations*:: Show the pending invitations. - -*/activity <jid>*:: Show the last activity of a contact or a server (its - uptime, in that case). - -*/server_cycle [server.tld] [message]*:: Disconnect and reconnect in all the - rooms of server.tld. - -*/bind <key> <eq>*:: Bind a key to another key or to a "command". For example, - "/bind ^H KEY_UP" makes Control + h behave the same way as the Up key. See the - link:keys.html[key bindings documentation page] for more details. - -*/runkey <key>*:: Execute the action defined for _key_. For example, - "/runkey KEY_PPAGE" will scroll up, or "/runkey ^N" will go to the next tab. - -*/self*:: Reminds you of who you are and what your status is. - -NOTE: The following command will work everywhere, except in the Roster tab. - -*/close*:: Close the tab. - -Chat tab commands -~~~~~~~~~~~~~~~~~ - -These commands will work in any conversation tab (MultiUserChat, Private, or - Conversation tabs). - -*/say <message>*:: Just send the message (only useful it you want your message - to begin with a _/_). Note that you can also send message starting with a _/_ - by starting it with _//_. - -*/xhtml <custom xhtml>*:: Send a custom xhtml message to the current tab. - -*/clear*:: Clear the current buffer. - -MultiUserChat tab commands -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*/ignore <nickname>*:: Ignore a specified nickname. - -*/unignore <nickname>*:: Remove the specified nickname from the ignore list. - -*/kick <nick> [reason]*:: Kick the user with the specified nickname. You can - also give an optional reason. - -*/topic <subject>*:: Change the subject of the room. You might want to knwow - that entering "/topic [tab]" will autocomplete the topic. - -*/query <nick> [message]*:: Open a private conversation with <nick>. This nick - has to be present in the room you’re currently in. If you specified a message - after the nickname, it will be sent to this user. - -*/part [message]*:: Disconnect you from a room. You can specify an optional - message. - -*/close [message]*:: Disconnect you from a room (if you are connected) and - close the tab. You can specify an optional message if you are still connected. - -*/nick <nickname>*:: Change your nickname in the current room. - *Except for gmail users* because gmail.com sucks and will do weird things - if you change your nickname in a MUC. - -*/recolor [random]*:: Re-assign a color to all the participants in the current - room, based on the last time they talked. Use this if the participants - currently talking have too many identical colors. If a random argument is - given, the participants will be shuffled before they are assigned a color. - -*/cycle [message]*:: Leave the current room an rejoint it immediatly. You can - specify an optional quit message. - -*/info <nickname>*:: Display some information about the user in the room: - his/her role, affiliation, status, and status message. - -*/version <nickname or jid>*:: Get the software version of the given nick in - room or the given jid (usually its XMPP client and Operating System). - -*/configure*:: Configure the current room through a form. - -*/names*:: Get the list of the users in the room, their number, and the list - of the people assuming different roles. - -Private tab commands -~~~~~~~~~~~~~~~~~~~~ - -*/info*:: Display some info about this user in the MultiUserChat. - -*/unquery*:: Close the tab. - -*/version*:: Get the software version of the current interlocutor (usually its - XMPP client and Operating System). - -Normal Conversation tab commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*/info*:: Display the status of this contact. - -*/unquery*:: Close the tab. - -*/version*:: Get the software version of the current interlocutor (usually its - XMPP client and Operating System). - -Roster tab commands -~~~~~~~~~~~~~~~~~~~ - -*/accept [jid]*:: Authorize the provided JID (or the selected contact in the - roster) to see your presence. - -*/deny [jid]*:: Prevent the provided JID (or the selected contact in the - roster) from seeing your presence. - -*/add <jid>*:: Add the specified JID to your roster and authorize him to see - your presence. If he accepts you, the subscription will be mutual (and if he - doesn’t, you can still /deny him). - -*/name <jid> <name>*:: Set the given JID’s name. - -*/groupadd <jid> <group>*:: Add the given JID to the given group (if the group - does not exist, it will be created). - -*/groupmove <jid> <old_group> <new_group>*:: Move the given JID from one group - to another (the JID has to be in the first group, and the new group may not - exist). - -*/groupremove <jid> <group>*:: Remove the given JID from the given group (if - the group is empty after that, it will get deleted). - -*/remove [jid]*:: Remove the specified JID from your roster. This will - unsubscribe you from its presence, cancel its subscription to yours, and - remove the item from your roster. - -*/reconnect*:: Disconnect from the remote server (if connected) and then - connect to it again. - -NOTE: The following commands only exist if your server supports them. If it -does not, you will be notified when you start poezio. - -*/block [jid]*:: Block the following JID using simple blocking. You will not - receive any of his messages and won’t be able to send some to him either. - -*/unblock [jid]*:: Unblock a previously blocked JID using simple blocking. You - will be able to send and receive messages from him again. - -*/list_blocks*:: List the blocked JIDs. - -NOTE: The following commands do not comply with any XEP or whatever, but they - can still prove useful when you are migrating to an other JID. - -*/export [/path/to/file]*:: Export your contacts into /path/to/file if - specified, or $HOME/poezio_contacts if not. - -*/import [/path/to/file]*:: Import your contacts from /path/to/file if - specified, or $HOME/poezio_contacts if not. - -XML tab commands -~~~~~~~~~~~~~~~~ - -*/clear*:: Clear the current buffer. diff --git a/doc/en/xep.txt b/doc/en/xep.txt deleted file mode 100644 index 019cd5b0..00000000 --- a/doc/en/xep.txt +++ /dev/null @@ -1,31 +0,0 @@ -XEP -=== - -.Table of all XEPs implemented in poezio. -[options="header"] -|========================================== -|XEP number|XEP name |Implementation status -|0004 |Data Forms |100% -|0012 |Last Activity| 100% -|0027 |Current Jabber OpenPGP Usage|100% -|0030 |Service Discovery|~100% -|0045 |Multi-User Chat|~90% -|0048 |Bookmarks|90% -|0059 |Result Set Management|~100% -|0071 |XHTML-IM|~70% -|0085 |Chat State Notifications|100% -|0092 |Software Version|100% -|0107 |User Mood|100% -|0108 |User Activity|100% -|0115 |Entity capabilities|~20% -|0118 |User Tune|90% -|0172 |User Nickname|100% -|0191 |Simple Communication Blocking|95% -|0196 |User Gaming|70% -|0199 |XMPP Ping|70% -|0202 |Entity time|100% -|0224 |Attention|100% -|0245 |The /me Command|80% -|0296 |Best Practices for Resource Locking|100% -|0308 |Last Message Correction|80% -|========================================== diff --git a/doc/images/conversation.png b/doc/images/conversation.png Binary files differdeleted file mode 100644 index 0940a3a4..00000000 --- a/doc/images/conversation.png +++ /dev/null diff --git a/doc/images/correct.png b/doc/images/correct.png Binary files differdeleted file mode 100644 index ed2ad450..00000000 --- a/doc/images/correct.png +++ /dev/null diff --git a/doc/images/data_forms.png b/doc/images/data_forms.png Binary files differdeleted file mode 100644 index 0afb3e03..00000000 --- a/doc/images/data_forms.png +++ /dev/null diff --git a/doc/images/layers.png b/doc/images/layers.png Binary files differdeleted file mode 100644 index 9ec71521..00000000 --- a/doc/images/layers.png +++ /dev/null diff --git a/doc/images/list.png b/doc/images/list.png Binary files differdeleted file mode 100644 index a2fc2315..00000000 --- a/doc/images/list.png +++ /dev/null diff --git a/doc/images/muc.png b/doc/images/muc.png Binary files differdeleted file mode 100644 index 8ddfff10..00000000 --- a/doc/images/muc.png +++ /dev/null diff --git a/doc/images/private.png b/doc/images/private.png Binary files differdeleted file mode 100644 index 19492e2b..00000000 --- a/doc/images/private.png +++ /dev/null diff --git a/doc/images/roster.png b/doc/images/roster.png Binary files differdeleted file mode 100644 index d1a8f9f4..00000000 --- a/doc/images/roster.png +++ /dev/null diff --git a/doc/images/simple_notify_example.png b/doc/images/simple_notify_example.png Binary files differdeleted file mode 100644 index 2e9c617c..00000000 --- a/doc/images/simple_notify_example.png +++ /dev/null diff --git a/doc/images/ssl_warning.png b/doc/images/ssl_warning.png Binary files differdeleted file mode 100644 index 348a81a4..00000000 --- a/doc/images/ssl_warning.png +++ /dev/null diff --git a/doc/images/tab_bar.png b/doc/images/tab_bar.png Binary files differdeleted file mode 100644 index 9c5c74eb..00000000 --- a/doc/images/tab_bar.png +++ /dev/null diff --git a/doc/images/theme_256_colors.png b/doc/images/theme_256_colors.png Binary files differdeleted file mode 100644 index 395f3d39..00000000 --- a/doc/images/theme_256_colors.png +++ /dev/null diff --git a/doc/images/vert_tabs.png b/doc/images/vert_tabs.png Binary files differdeleted file mode 100644 index a48a8051..00000000 --- a/doc/images/vert_tabs.png +++ /dev/null diff --git a/doc/poezio.txt b/doc/poezio.txt deleted file mode 100644 index 47497434..00000000 --- a/doc/poezio.txt +++ /dev/null @@ -1,83 +0,0 @@ -Poezio documentation -==================== - -This page is the documentation for poezio. - -Poezio is an XMPP console client mostly written in python and a little -bit in C. - -It uses curses to draw its user interface. - -It has been written to create an XMPP client that could very easily be used by -any IRC user. Its interface tries to be like the ones of famous clients such -as irssi or weechat. - -:numbered: -== Usage == - -Poezio is composed of tabs which can be of various types. Each tab type has -a distinct interface, list of commands and list of key shortcuts, in addition -to the global commands and key shortcuts. - - -=== Commands === - -Commands start with the */* character and can take a list of any number -of arguments, separated by spaces. If an argument should contain a space, -you can use the *"* character to surround this argument. - -.The command nick with only one argument -========================================== -/nick "my new nick" -========================================== - -.The command status with two arguments -========================================== -/status away "on vacation" -========================================== - -.Note -The character *'* cannot be used instead of *"*. - - -To know the list of all available commands, use the *help* command with no -argument. To know more about the command (what it does and how to use it), -use the *help* command and pass the command name as its first argument. - -The list of all global commands is as follow: - -[horizontal] -*help*:: [command_name] + - Displays the list of all available commands in the current tab, or displays - the usage of the given command. -*message*:: <jid> [message] + - Open a conversation with the specified JID, and send a message to it, - if specified. - - - - - -.Get information on the status command -========================================== -/help status -========================================== - - -=== Tabs === -This section lists and describes all the tab types. - - -==== Roster Tab ==== -This is the first tab that you will see when starting poezio. - -It contains your roster - -[glossary] -== Glossary == - -This glossary explains some terms that are used in this documentation. - -[glossary] -Roster:: - The list of contacts, sorted by groups, status, or anything the client wishes. diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..c0badf1d --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,249 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Poezio Plugin development documentation build configuration file, created by +# sphinx-quickstart on Mon Mar 4 23:39:07 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os +sys.path.insert(0, os.path.abspath('../stub')) +sys.path.append(os.path.abspath('../../src/')) + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Poezio Plugin development' +copyright = '2013, Mathieu Pasquet - Florent Le Coz' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ['.'] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'PoezioPlugindevelopmentdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'PoezioPlugindevelopment.tex', 'Poezio Plugin development Documentation', + 'Mathieu Pasquet - Florent Le Coz', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'poezioplugindevelopment', 'Poezio Plugin development Documentation', + ['Mathieu Pasquet - Florent Le Coz'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'PoezioPlugindevelopment', 'Poezio Plugin development Documentation', + 'Mathieu Pasquet - Florent Le Coz', 'PoezioPlugindevelopment', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/doc/source/dev/common.rst b/doc/source/dev/common.rst new file mode 100644 index 00000000..f9ee7c77 --- /dev/null +++ b/doc/source/dev/common.rst @@ -0,0 +1,8 @@ +Common operations documentation +=============================== + +.. automodule:: common + :members: + :undoc-members: + + diff --git a/doc/source/dev/events.rst b/doc/source/dev/events.rst new file mode 100644 index 00000000..c2aa4036 --- /dev/null +++ b/doc/source/dev/events.rst @@ -0,0 +1,142 @@ +Event Index +=========== + +The following events are poezio-only events, for SleekXMPP events, check out +`their index <http://sleekxmpp.com/event_index.html>`_. + +.. glossary:: + :sorted: + + muc_say + - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered whenever the user sends a message to a :py:class:`~tabs.MucTab`. + + muc_say_after + - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **tab:** :py:class:`~tabs.MucTab` source + + Same thing than :term:`muc_say`, but after XHTML generation of the body, if needed. + This means you must not insert any colors in the body in the handler, since + it may lead to send invalid XML. This hook is less safe than ``muc_say`` and + you should probably not need it. + + private_say + - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **tab:** :py:class:`~tabs.PrivateTab` source + + Triggered whenever the user sends a message to a :py:class:`~tabs.PrivateTab`. + + private_say_after + - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **tab:** :py:class:`~tabs.PrivateTab` source + + Same thing than :term:`private_say`, but after XHTML generation of the body, if needed. + This means you must not insert any colors in the body in the handler, since + it may lead to send invalid XML. This hook is less safe than :term:`private_say` and + you should probably not need it. + + conversation_say + - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **tab:** :py:class:`~tabs.ConversationTab` source + + Triggered whenever the user sends a message to a :py:class:`~tabs.ConversationTab`. + + conversation_say_after: + - **message:** :py:class:`~sleekxmpp.Message` that will be sent + - **tab:** :py:class:`~tabs.ConversationTab` source + + Same thing than :term:`conversation_say`, but after XHTML generation of the body, if needed. + This means you must not insert any colors in the body in the handler, since + it may lead to send invalid XML. This hook is less safe than :term:`conversation_say` and + you should probably not need it. + + muc_msg + - **message:** :py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when a message is received in a :py:class:`~tabs.MucTab`. + + private_msg + - **message:** :py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`~tabs.PrivateTab` source + + Triggered when a message is received in a :py:class:`~tabs.PrivateTab`. + + conversation_msg + - **message:** :py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`~tabs.ConversationTab` source + + Triggered when a message is received in a :py:class:`~tabs.ConversationTab`. + + conversation_chatstate + - **message:** :py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`~tabs.ConversationTab` source + + Triggered when a chatstate is received in a :py:class:`~tabs.ConversationTab`. + + muc_chatstate + - **message:** :py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when a chatstate is received in a :py:class:`~tabs.MucTab`. + + private_chatstate + - **message:** :py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`PrivateTab <tabs.PrivateTab>` source + + Triggered when a chatstate is received in a :py:class:`~tabs.PrivateTab`. + + normal_presence + - **presence:** :py:class:`~sleekxmpp.Presence` received + - **resource:** :py:class:`Resource <str>` that emitted the :py:class:`~sleekxmpp.Presence` + + Triggered when a presence is received from a contact. + + muc_presence + - **presence:** :py:class:`~sleekxmpp.Presence` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when a presence is received from someone in a :py:class:`~tabs.MucTab`. + + send_normal_presence + - **presence:** :py:class:`~sleekxmpp.Presence` sent + + Triggered when before poezio sends a new :py:class:`~sleekxmpp.Presence` stanza. + + muc_join + - **presence:** :py:class:`~sleekxmpp.Presence` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when an user joins a :py:class:`~tabs.MucTab` + + muc_ban + - **presence:** :py:class:`~sleekxmpp.Presence` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when an user from a :py:class:`~tabs.MucTab` + gets banned. + + muc_kicked + - **presence:** :py:class:`~sleekxmpp.Presence` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when an user from a :py:class:`~tabs.MucTab` + gets kicked. + + muc_nickchange + - **presence:** :py:class:`~sleekxmpp.Presence` received + - **tab:** :py:class:`~tabs.MucTab` source + + Triggered when an user in a :py:class:`~tabs.MucTab` changes + his nickname. + + ignored_private + - **message**:py:class:`~sleekxmpp.Message` received + - **tab:** :py:class:`~tabs.PrivateTab` source + + Triggered when a private message (that goes in a :py:class:`~tabs.PrivateTab`) + is ignored automatically by poezio. + + **tab** is always ``None``, except when a tab has already been opened. diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst new file mode 100644 index 00000000..7498e0e8 --- /dev/null +++ b/doc/source/dev/index.rst @@ -0,0 +1,19 @@ +.. Poezio Plugin development documentation master file, created by + sphinx-quickstart on Mon Mar 4 23:39:07 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Development documentation +========================= + +Contents: + +.. toctree:: + :maxdepth: 2 + + plugin + events + timed_events + common + sleek + diff --git a/doc/source/dev/plugin.rst b/doc/source/dev/plugin.rst new file mode 100644 index 00000000..7978a5e9 --- /dev/null +++ b/doc/source/dev/plugin.rst @@ -0,0 +1,41 @@ +Plugin API documentation +======================== + +.. module:: plugin + +.. autoclass:: BasePlugin + :members: init, cleanup, api, core + + .. method:: init(self) + + Method called at the creation of the plugin. + + Do not override __init__ and use this instead. + + .. method:: cleanup(self) + + Method called before the destruction of the plugin. + + Use it to erase or save things before the plugin is disabled. + + .. attribute:: core + + The Poezio :py:class:`~Core` object. Use it carefully. + + .. attribute:: api + + The :py:class:`~PluginAPI` instance for this plugin. + + +Each plugin inheriting :py:class:`~BasePlugin` has an ``api`` member variable, which refers +to a :py:class:`~PluginAPI` object. + +The :py:class:`~PluginAPI` object is an a interface through which the :py:class:`~BasePlugin` +(and inheritors) *should* go to interact with poezio. If it is not sufficient, then the ``core`` +member can be used. + +.. autoclass:: PluginAPI + :members: + :undoc-members: + + diff --git a/doc/source/dev/sleek.rst b/doc/source/dev/sleek.rst new file mode 100644 index 00000000..7baf5b29 --- /dev/null +++ b/doc/source/dev/sleek.rst @@ -0,0 +1,16 @@ +SleekXMPP classes +================= + +.. module:: sleekxmpp + +.. autoclass:: Message + :members: + +.. autoclass:: Presence + :members: + +.. autoclass:: Iq + :members: + + + diff --git a/doc/source/dev/timed_events.rst b/doc/source/dev/timed_events.rst new file mode 100644 index 00000000..a2c96912 --- /dev/null +++ b/doc/source/dev/timed_events.rst @@ -0,0 +1,17 @@ +Timed events documentation +========================== + +.. automodule:: timed_events + +.. autoclass:: TimedEvent + + .. automethod:: __init__ + .. automethod:: has_timed_out + .. automethod:: change_date + .. automethod:: add_delay + + +.. autoclass:: DelayedEvent + + .. automethod:: __init__ + diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..1b621e5a --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,35 @@ +.. Poezio Plugin development documentation master file, created by + sphinx-quickstart on Mon Mar 4 23:39:07 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Poezio documentation +==================== + +Contents: + +.. toctree:: + :maxdepth: 1 + + install + themes + dev/index + +.. + configure + ssl + usage + themes + keys + plugins + misc + xep + dev + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/source/install.rst b/doc/source/install.rst new file mode 100644 index 00000000..45330dc6 --- /dev/null +++ b/doc/source/install.rst @@ -0,0 +1,129 @@ +Installing Poezio +================= + + +.. important:: 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*: `Sekh’s overlay`_ contains everything required to build poezio + (sleekxmpp, dnspython, and poezio) +- *Debian*: Use an other distro. (or make a package, we can provide help :) ) + +(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 `stable sources`_, or fetch the development +version (trunk), using git: + +.. code-block:: bash + + 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 `SleekXMPP`_ + page and the `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, use the following +instructions. Else, go to the :ref:`next section <poezio-install-label>` (recommended). + + +Download SleekXMPP + +.. code-block:: bash + + git clone git://github.com/fritzy/SleekXMPP.git + +Make sure you're using the develop branch by typing + +.. code-block:: bash + + cd SleekXMPP + git checkout develop + +Install SleekXMPP with + +.. code-block:: bash + + python3 setup.py build + su -c "python3 setup.py install" + +Install the dnspython3 package on your distribution or install it manually: + +.. code-block:: bash + + 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: + +.. code-block:: bash + + python3 setup.py build + su -c "python3 setup.py install" + +.. _poezio-install-label: + +""""""""""""""""""" +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: + +.. code-block:: bash + + ./update.sh + +If you have git installed, it will download and update locally the + libraries for you. (and if you don’t have git installed, install it) + + +If you don't want to install poezio but just test it (or keep a development + version), do: + +.. code-block:: bash + + ./launch.sh + +To install poezio, do, as root (or sudo with ubuntu or whatever): + +.. code-block:: bash + + make install + +And then start it with: + +.. code-block:: bash + + poezio + +.. _Sekh’s overlay: https://github.com/sekh/sekh_overlay +.. _stable sources: https://dev.louiz.org/project/poezio/download +.. _SleekXMPP: https://github.com/fritzy/SleekXMPP/ +.. _dnspython: http://www.dnspython.org/ diff --git a/doc/source/themes.rst b/doc/source/themes.rst new file mode 100644 index 00000000..98b5f13e --- /dev/null +++ b/doc/source/themes.rst @@ -0,0 +1,108 @@ +Themes +====== + +This page describes how themes work in poezio and how to create or +modify one. + +A theme contains color attributes and character definitions. Poezio can display +up to **256** colors if your terminal supports it. Most of the time, +if it doesn’t work, that’s because the **$TERM** environnment variable is +wrong. For example with tmux or screen, set it to **screen-256color**, in +**xterm**, set it to **xterm-256color**, etc. + +If your terminal doesn’t have 256 colors, only 8 colors will be available, +and poezio will replace the colors by one of the 8 values available. +Thus, some theme files may not work properly if you only have 8 colors, +for example light gray on dark gray may be converted to black on black, making +the text impossible to read). + +.. note:: The default theme should work properly in any case. If not, that’s a bug. + +A theme file is a python file (with the .py extension) containing a +class, inheriting the *theming.Theme* class defined into the *theming* +poezio module. + +To check how may colors your current terminal/$TERM supports, do: + +.. code-block:: bash + + tput colors + + +Create a theme +-------------- + +To create a theme named foo, create a file named foo.py into the theme +directory (by default it’s _~/.local/share/poezio/themes/_) and insert +into it: + +.. code-block:: python + + import theming + + class FooTheme(theming.Theme): + # Define here colors for that theme + theme = FooTheme() + +To define a *color pair* and assign it to the *COLOR_NAME* option, just do + +.. code-block:: python + + class FooTheme(theming.Theme): + COLOR_NAME = (fg_color, bg_color, opt_attr) + +You do not have to define all the :ref:`available options`, +you can decide that your theme will only change some options, the other +one will just have the default value (from the default theme). + +Colors and attributes +~~~~~~~~~~~~~~~~~~~~~ +A color pair defines how the text will be displayed on the screen. It +has a *foreground color* (fg_color), a *background color* (bg_color) +and an **optional** *attribute* (opt_attr). + +Colors +^^^^^^ +A color is a number between -1 and 255. If it -1, this is the default +color defined by your terminal (for example if your terminal displays +text white on black by default, a fg_color of -1 is white, and a bg_color +of -1 is black). If it’s between 0 and 256 it represents one of the colors +on the image: + +.. figure:: ../images/theme_256_colors.png + :alt: The list of all 256 colors + + The list of all 256 colors + +Attributes +^^^^^^^^^^ +An attribute is a python string (so, it has to be surrounded by +*" "* or *' '*). It can be one of the following: + +- *'b'*: bold text +- *'u'*: underlined text + +Use a theme +----------- +To use a theme, just define the **theme** option into the +*configuration file* to the name of the theme you want +to use. If that theme is not found, the default theme will be used instead. +Note that the default theme is defined directly into poezio’s source code, +and not in a theme file. + +Change the theme directory +-------------------------- +To change the default theme directory (**~/.local/share/poezio/themes/** by +default), you have to change the *themes_dir* option in the +*configuration file* to the directory that contains your +theme files. + +.. _available-options: + +Available options +----------------- + +.. warning:: This section is not complete. + +All available options can be found into the default theme, which is into the +_theming.py_ file from the poezio’s source code. diff --git a/doc/stub/args.py b/doc/stub/args.py new file mode 100644 index 00000000..4691a224 --- /dev/null +++ b/doc/stub/args.py @@ -0,0 +1,34 @@ +""" +Module related to the argument parsing + +There is a fallback to the deprecated optparse if argparse is not found +""" +from os import path + +def parse_args(CONFIG_PATH=''): + """ + Parse the arguments from the command line + """ + try: + from argparse import ArgumentParser, SUPPRESS + except ImportError: + from optparse import OptionParser + from optparse import SUPPRESS_HELP as SUPPRESS + parser = OptionParser() + parser.add_option("-f", "--file", dest="filename", default=path.join(CONFIG_PATH, 'poezio.cfg'), + help="The config file you want to use", metavar="CONFIG_FILE") + parser.add_option("-d", "--debug", dest="debug", + help="The file where debug will be written", metavar="DEBUG_FILE") + parser.add_option("-v", "--version", dest="version", + help=SUPPRESS, metavar="VERSION", default="0.8-dev") + (options, args) = parser.parse_args() + else: + parser = ArgumentParser() + parser.add_argument("-f", "--file", dest="filename", default=path.join(CONFIG_PATH, 'poezio.cfg'), + help="The config file you want to use", metavar="CONFIG_FILE") + parser.add_argument("-d", "--debug", dest="debug", + help="The file where debug will be written", metavar="DEBUG_FILE") + parser.add_argument("-v", "--version", dest="version", + help=SUPPRESS, metavar="VERSION", default="0.8-dev") + options = parser.parse_args() + return options diff --git a/doc/stub/config.py b/doc/stub/config.py new file mode 100644 index 00000000..4ad01f7a --- /dev/null +++ b/doc/stub/config.py @@ -0,0 +1,224 @@ +# Copyright 2010-2011 Florent Le Coz <louiz@louiz.org> +# +# This file is part of Poezio. +# +# Poezio is free software: you can redistribute it and/or modify +# it under the terms of the zlib license. See the COPYING file. + +""" +Defines the global config instance, used to get or set (and save) values +from/to the config file +""" + +DEFSECTION = "Poezio" + +from configparser import RawConfigParser, NoOptionError, NoSectionError +from os import environ, makedirs, path +from shutil import copy2 +from args import parse_args +from common import safeJID + + +class Config(RawConfigParser): + """ + load/save the config to a file + """ + def __init__(self, file_name): + self.file_name = file_name + RawConfigParser.__init__(self, None) + # make the options case sensitive + self.optionxform = str + try: + RawConfigParser.read(self, file_name, encoding='utf-8') + except TypeError: # python < 3.2 sucks + RawConfigParser.read(self, file_name) + # Check config integrity and fix it if it’s wrong + for section in ('bindings', 'var'): + if not self.has_section(section): + self.add_section(section) + + def get(self, option, default, section=DEFSECTION): + """ + get a value from the config but return + a default value if it is not found + The type of default defines the type + returned + """ + try: + if type(default) == int: + res = self.getint(option, section) + elif type(default) == float: + res = self.getfloat(option, section) + elif type(default) == bool: + res = self.getboolean(option, section) + else: + res = self.getstr(option, section) + except (NoOptionError, NoSectionError): + return default + return res + + def getl(self, option, default, section=DEFSECTION): + """ + get a value and return it lowercase + """ + return self.get(option, default, section).lower() + + def get_by_tabname(self, option, default, tabname, fallback=True, fallback_server=True): + """ + Try to get the value for the option. First we look in + a section named `tabname`, if the option is not present + in the section, we search for the global option if fallback is + True. And we return `default` as a fallback as a last resort. + """ + if tabname in self.sections(): + if option in self.options(tabname): + # We go the tab-specific option + return self.get(option, default, tabname) + if fallback_server: + return self.get_by_servname(tabname, option, default, fallback) + if fallback: + # We fallback to the global option + return self.get(option, default) + return default + + def get_by_servname(self, jid, option, default, fallback=True): + """ + Try to get the value of an option for a server + """ + server = safeJID(jid).server + if server: + server = '@' + server + if server in self.sections() and option in self.options(server): + return self.get(option, default, server) + if fallback: + return self.get(option, default) + return default + + + def __get(self, option, section=DEFSECTION): + """ + facility for RawConfigParser.get + """ + return RawConfigParser.get(self, section, option) + + def getstr(self, option, section=DEFSECTION): + """ + get a value and returns it as a string + """ + return self.__get(option, section) + + def getint(self, option, section=DEFSECTION): + """ + get a value and returns it as an int + """ + try: + return int(self.__get(option, section)) + except ValueError: + return -1 + + def getfloat(self, option, section=DEFSECTION): + """ + get a value and returns it as a float + """ + return float(self.__get(option, section)) + + def getboolean(self, option, section=DEFSECTION): + """ + get a value and returns it as a boolean + """ + return RawConfigParser.getboolean(self, section, option) + + def write_in_file(self, section, option, value): + """ + Our own way to save write the value in the file + Just find the right section, and then find the + right option, and edit it. + + TODO: make it write also new values in the file, not just what did already + exist + """ + if path.exists(self.file_name): + df = open(self.file_name, 'r', encoding='utf-8') + lines_before = (line.strip() for line in df.readlines()) + df.close() + else: + lines_before = [] + result_lines = [] + we_are_in_the_right_section = False + written = False + section_found = False + for line in lines_before: + if line.startswith('['): # check the section + if we_are_in_the_right_section and not written: + result_lines.append('%s = %s' % (option, value)) + written = True + if line == '[%s]' % section: + we_are_in_the_right_section = True + section_found = True + else: + we_are_in_the_right_section = False + if (line.startswith('%s ' % (option,)) or + line.startswith('%s=' % (option,)) or + line.startswith('%s = ' % (option,))) and we_are_in_the_right_section: + line = '%s = %s' % (option, value) + written = True + result_lines.append(line) + + if not section_found: + result_lines.append('[%s]' % section) + result_lines.append('%s = %s' % (option, value)) + elif not written: + result_lines.append('%s = %s' % (option, value)) + + + df = open(self.file_name, 'w', encoding='utf-8') + for line in result_lines: + df.write('%s\n' % line) + df.close() + + def set_and_save(self, option, value, section=DEFSECTION): + """ + set the value in the configuration then save it + to the file + """ + # Special case for a 'toggle' value. We take the current value + # and set the opposite. Warning if the no current value exists + # or it is not a bool. + if value == "toggle": + current = self.get(option, "", section) + if current.lower() == "false": + value = "true" + elif current.lower() == "true": + value = "false" + else: + return "Could not toggle option: %s. Current value is %s." % (option, current or "empty") + if self.has_section(section): + RawConfigParser.set(self, section, option, value) + else: + self.add_section(section) + RawConfigParser.set(self, section, option, value) + self.write_in_file(section, option, value) + return "%s=%s" % (option, value) + + + def set(self, option, value, section=DEFSECTION): + """ + Set the value of an option temporarily + """ + try: + RawConfigParser.set(self, section, option, value) + except NoSectionError: + pass + + +# creates the configuration directory if it doesn't exist +# and copy the default config in it + +#options = parse_args(CONFIG_PATH) +class Stub(object): + def __getattribute__(self, v): + def stub_func(self, *args, **kwargs): return '' + return stub_func + +options = Stub() +config = Stub() |
