From 16ca71fe143f84c750cd380cae2156879b67bed9 Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Fri, 22 Jan 2010 20:49:21 -0200 Subject: [PATCH] Documented all options now --- CHEAT-CODES | 124 ++++++++++++++++++++++++++++++++++ docs/CHEAT-CODES.rst | 1 + docs/index.rst | 3 +- mitterlib/network/__init__.py | 22 ++---- mitterlib/network/twitter.py | 35 +--------- mitterlib/ui/ui_pygtk.py | 30 +------- 6 files changed, 134 insertions(+), 81 deletions(-) create mode 100644 CHEAT-CODES create mode 120000 docs/CHEAT-CODES.rst diff --git a/CHEAT-CODES b/CHEAT-CODES new file mode 100644 index 0000000..0804013 --- /dev/null +++ b/CHEAT-CODES @@ -0,0 +1,124 @@ +======================== +Hidden options in Mitter +======================== + +Mitter have some options that are not completely visible to the user. +Those options reside in the config file (usually ``.mitter.ini`` in +the user home directory) and can affect the application behaviour or +appearance. + +Config Format +============= +Before changing anything, you must be aware of the format of the +config file. It's a format called "INI file", where options are +separated by sections. Sections have square brackets around them while +options have an equal sign separating the option name and the option +value. Here is a small example, with a section called *Section* and an +option called *option* with the value *value*:: + + [Section] + option = value + + +Network Manager +=============== +The Network Manager is responsible for managing all the network layers +and provide a single point of access to them for the interfaces. The +network manager uses the ``NetworkManager`` section: + +*timeout* + Timeout for requests, in seconds. This value is (or should) be + used by all networks. If a quests takes longer than those seconds, + it will be canceled and the result, a failure. Default value is + 120. + +*save_count* + Number of operations till the configuration file is saved again. + Most networks will save their status in the config file, but not + request it to be saved immediately (nor should they: In case + something wrong happens, the state in the config file will not be + reasonable when mitter is run again.) A value of 0 means the + Network Manager will save the config file after each round of + requests to all networks (failing or succeding); for devices that + use flash drives as storage, it's recommended some large value + (since those storage devices have a lifetime based on the number + of writes.) Default is '5'. + +Twitter +======= +Twitter is the most famous micro-blogging website and the original +network supported by Mitter. It have the following options: + +*https* + A boolean value (can accept either "True" or "False" as values) + indicating that HTTPS (secure HTTP) should be used. + +*server_url* + Points to the URL to be used for insecure requests. If *https* is + False, all requests will go to this URL. + +*secure_server_url* + Points to the URL to be used for secure requests. If *https* is + True, all requests will go to this URL. + +*last_tweet* + Twitter supports a "since_id" on requests, allowing less (or more) + requests to be made to retrieve information since the last time + the user saw their messages. Mitter uses it on every request to + get just the new messages instead of everything (and not miss any + tweets in case you leave Mitter close for awhile.) If this value + is does not exist in the config file, Mitter will request only the + first page and update this values. + +*last_reply* + Works exactly like *last_tweet*, except for replies. + +*message_threshold* + Twitter uses 20 messages per page, but due their caching mecanism, + some pages may have less than 20 message on each page (in other + words, it works like this: they have the result pages set already, + but when you request something, they finally check if there are + deleted tweets in it and, if there are any, they are removed + there, but no new messages are added.) If the number of messages + is below the threshold, Mitter will not request the next page. The + default value is '16', or 80% of the default page size. + +PyGTK +===== +PyGTK is the default graphical interface. It have the following +options: + +*refresh_interval* + The refresh interval to check for new messages, in minutes. + Default value is '5'. + +*statusicon* + Display the status icon in the systray. Default is True. + +*width* + Window width, in pixels. It stars with 450, but it's updated when + Mitter closes. + +*height* + Window height, in pixels. It starts with 300, but it's updated + when Mitter closes. + +*position_x* + Horizontal position of the window in the screen. It starts with 5, + but it's saved when Mitter closes. + +*position_y* + Vertical position of the window in the screen. It starts with 5, + but it's saved when Mitter closes. + +*link_colour* + Color to be used when displaying links. Default value is 'blue'; + it accepts any X11 named colours or hex triplests (like the ones + used in HTML.) + +*spell_check* + Boolean indicating if the spell checker should be used. To have + spell checkers enabled, you must have PyAspell installed, so it's + checked once and, if PyAspell is not installed, will be set as + False and not checked again. If you install PyAspell after Mitter + is run the first time, you must manually update this value. diff --git a/docs/CHEAT-CODES.rst b/docs/CHEAT-CODES.rst new file mode 120000 index 0000000..ed4af28 --- /dev/null +++ b/docs/CHEAT-CODES.rst @@ -0,0 +1 @@ +../CHEAT-CODES \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 3092d8e..d0e0db9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,8 +13,7 @@ User Documentation README INSTALL HACKING - - twitter + CHEAT-CODES Developer Documentation: diff --git a/mitterlib/network/__init__.py b/mitterlib/network/__init__.py index a2b958e..394f8e4 100644 --- a/mitterlib/network/__init__.py +++ b/mitterlib/network/__init__.py @@ -28,24 +28,6 @@ _log = logging.getLogger('mitterlib.network.Networks') # List of files that are not networks SKIPPABLES = ('__init__.py', 'networkbase.py') -"""The network manager, besides managing the other networks and their options, -have the following options: - -*timeout* - Timeout for requests, in seconds. This value is (or should) be used to all - networks. Default value is '120'. - -*save_count* - Number of operations till the configuration file is saved again. Most - networks will save their status in the config file, but not request it to be - saved immediately (nor should they, 'cause they can save a weird state in - case the next network causes Mitter to crash or something related.) A value - of 0 means the Network Manager will save the config file after each round of - requests to all networks (failing or succeding); for devices that use flash - drives as storage, it's recommended some large value (since those storage - devices have a lifetime based on the number of writes.) Default is '5'. -""" - #-------------------------------------------------------------------- # Helper functions #-------------------------------------------------------------------- @@ -162,6 +144,10 @@ class Networks(object): return result def options(self): + """Add the options for all networks and the network manager options + itself.""" + # Remember that, in case you add or remove any options here, you + # should also update the CHEAT-CODES file. for shortcut in self.networks: conn = self.networks[shortcut] conn.options(self._options) diff --git a/mitterlib/network/twitter.py b/mitterlib/network/twitter.py index f385005..dbdb952 100644 --- a/mitterlib/network/twitter.py +++ b/mitterlib/network/twitter.py @@ -43,39 +43,6 @@ except ImportError: # Fallback to SimpleJSON import simplejson as json -""" -The Twitter network layer have the following options: - -*last_tweet* - Last tweet seen in the home timeline request. It's used to not request the - whole timeline again. Usually, it should not be manually changed. Starts - with no value, meaning it will request only the first page; after that, it - will requests all tweets, no matter how many pages it is necessary, since - the last seen tweet. - -*last_reply* - Last reply seen in the replies timeline. Works exactly the same as - *last_tweet*, but with replies timeline. - -*server_url* - URL for the non-secure server. Can include any paths. Default value is - 'http://api.twitter.com/1'. - -*secure_server_url* - URL for the secure server. Can include any paths. Default value is - 'https://api.twitter.com/1'. - -*threshold* - Threshold for not requesting the next page. If the number of returned - elements is below this number, the module will not request the next page. - This is due the way Twitter uses its cache: In a normal operation, any page - that have less than the default 20 elements per page can be considered the - last page; due the caching policy Twitter uses, some pages will have less - than those 20 elements (it first retrieves the 20 elements, then checks if - there are any deleted elements -- if there are, those are removed but no new - elements are added to the result.) Default value is '16' (80% of a full - page.) -""" # ---------------------------------------------------------------------- # I18n bits # ---------------------------------------------------------------------- @@ -313,6 +280,8 @@ class Connection(NetworkBase): @classmethod def options(self, options): """Add options related to Twitter.""" + # Rememeber to update the CHEAT-CODES file if you add/remove any + # options. options.add_group(self.NAMESPACE, 'Twitter network') options.add_option('-s', '--no-https', group=self.NAMESPACE, diff --git a/mitterlib/ui/ui_pygtk.py b/mitterlib/ui/ui_pygtk.py index 4409c29..1d37e9c 100644 --- a/mitterlib/ui/ui_pygtk.py +++ b/mitterlib/ui/ui_pygtk.py @@ -37,34 +37,6 @@ from mitterlib.ui.helpers.image_helpers import find_image from mitterlib.constants import gpl_3, version from mitterlib.ui.helpers import timesince -""" -PyGTK interface internal options: - -*width* - Width of the main window, in pixels. Default value is '450', but this value - is saved when Mitter is closed and reloaded when it's run again. - -*height* - Height of the main window, in pixels. Default value is '300' but it is saved - when Mitter is closed and reloaded when it's run again. - -*position_x* - X position of the main window. Default value is '5' but it is saved when - Mitter is closed and reloaded when it's run again. - -*position_y* - Y position of the main window. Default value is '5' but it is saved when - Mitter is closed and reloaded when it's run again. - -*link_colour* - Colour for displaying links. Default value is 'blue'. You can use valid X11 - colour names or hex-triplets (as used in HTML, e.g., #0000ff. -- you need to - include the hash in those cases.) - -*spell_check* - Boolean indicating if spell checker is enabled. Mitter will try to activate - it the first time it's run, but it requires Aspell and its Python bindings. -""" # Constants @@ -1460,6 +1432,8 @@ class Interface(object): @classmethod def options(self, options): """Add the options for this interface.""" + # Remember to update CHEAT-CODES in case you add or remove any + # options. options.add_group(self.NAMESPACE, 'GTK+ Interface') options.add_option('--refresh-interval', group=self.NAMESPACE,