update the man page

1 files changed, 65 insertions, 22 deletions

diff --git a/doc/fakplugin.1 b/doc/fakplugin.1
index ca1d958..f602a83 100644
--- a/doc/fakplugin.1
+++ b/doc/fakplugin.1
@@ -8,8 +8,7 @@ It also contains useful information to develop a plugin for firstaidkit.
 .SH "Plugin Suffixes"
 All plugins belong to configured plugin directory. Recognized suffixes are: .py, .pyc, 
 .pyo (python modules) and .so (python compatible binary module).  The plugins should be 
-placed in a default location (/usr/lib/firstaidkit-plugins, the lib directory changes to 
-lib64 when in a 64 bit arch).
+placed in a default location (/usr/{lib,lib64}/firstaidkit-plugins).
 .\"Should mention the /etc/firstaidkit.conf file.  Should include multiple plugin source dirs.\"
 
 .SH "Plugin Model"
@@ -17,18 +16,14 @@ The building blocks of the plugins are functions and flows.  A function is a cer
 that is taken inside the plugin.  This action is more or less independent from the rest of 
 the plugin actions.  Things like fix, backup, restore... qualify as actions/functions.  
 This does not mean that functions do not relate to each other.  They are related by using 
-the flow structure.
+the flow data structure (The data structure used for the flows is a dictionary).
 
 A flow is the organization of functions in a directional graph that defines the "flow" of 
-functions.  Understand flow here as the order in which each function is executed when the 
+functions.  Understand flow here as the order in which functions are executed when the 
 plugin is used.  This order/flow is specified using the function names, their return codes 
-and the flow structure.  All this is contained within a dictionary (The Examples Sections 
+and the flow data structure.  All this is contained within a dictionary (The Examples Sections 
 shows how this is done.)
 
-Please take into account as you code your plugin to set the _result and the _state values 
-in your main plugin class.  These values are necessary to correctly execute the flow given 
-by the flow dictionary.
-
 .SH "Coding a Plugin"
 .IP "1. Class methods and class attributes:"
 The main plugin class has some class methods and some class attributes. These elements are 
@@ -36,13 +31,18 @@ used to describe the plugin and are used without actually using a instance of th
 This is important because we do not want to execute the __init__ function and cause lots of 
 unnecessary  stuff to go into memory when we are querying for plugin basic information.
 
-The class attributes are: name, version, author, initial (Initial state for all flows), final 
-(Final state for all flows), flows (The flows defined by the Plugin class), default_flow (is 
-the name of the flow used in automatic repair mod).
+The class attributes are: name, version, author and the defined flows.  For the information
+to be displayed correctly to the user the plugin developer must include at least name, version
+and author as class attributes.  The flows attribute is not necesarry if custom flows aren't
+present.  If the plugin developer is planning to create a custom flows he must declare the flows 
+dictionary for your plugin.  More information of the class attributes in the "Class Attribute"
+section.
 
-The class attributes are: info() (returns the name, version and author  in a tuple), getDeps() 
+The class methods are: info() (returns the name, version and author  in a tuple), getDeps() 
 (returns list of required flags for automated mode) and getFlows() (returns a list of possible 
-flow names that the plugin can execute).
+flow names that the plugin can execute).  The plugin developer doesn't really have to worry
+about the methods as they are defined in the father class Plugin.  Section "Class Methods"
+gives more infor on each one.
 
 .IP "2. Plugin dependencies"
 You can also specify flags, which are required to be satisfied before the automated mode can 
@@ -53,15 +53,33 @@ class method.  Setting flags is also easy. Just use the provide() method common
 See section "Common stuff for plugins"
 
 .IP "4. Flows:"
-If you want to redefine or add your own flows into your plugin, you must initialize the parent 
-class (Plugin) in your __init__.  And begin to add your personalized flows to the flows 
-variable.  The examples section shows how to add a flow.
+There are two basic flows hardcoded into the system. These flows may *not* be used by plugin
+developers.  The first flow is called diagnose: the intention with this flow is to give the
+user information of the state of the system that the plugin is analysing.  This flow is
+intended to give general information and needs to be very fast.  If the plugin needs to do
+some more detailed diagnose analysis, we suggest to create another flow called 'detailedAnalysis'.
+When coding the diagnose flow, remember that it will be executed when the user asks for the
+information of *all* the plugins.  The diagnose flow calls only the diagnose task.  
+The seconf flow is called fix:  the intention with this flow is to actually fix whatever 
+is wrong with the system.  We suggest this flow to be as thorough as it needs to be.  If there
+is more than one way to fix the problem, this flow would be the easiest one (the plugin
+developer can create other flow for the more complex ones).  For this flow to be successfull
+the prepare, diagnose, backup, fix, restore and clean tasks must be present in the plugin.  
+for more info see section "Common stuff for plugins".  Finally, to add a custom flow the
+plugin developer must define a dictionary named flows (flows = {}) and fill it with the custom
+flows.  For more info on adding flows see the "Examples" section.
 
 .IP "5. self._result and self._state
 These are the two variables that define the location of the plugin inside the flow dictionary.  
 In each function, after it has done its intended action, the self._result variable must be 
-changed to a correct value.  This value will define the next self._state value inside the plugin.  
-The self._state value is change using the flow dictionary and the self._result value.
+changed to a correct value.  Think of the self._result as the return value of each task.  The
+self._result usually takes a firstaidkit return value (classes that define the return value).
+firstaidkit comes with predifined return value classes but the plugin developer may define his
+own return classes.  One reason to define a custom return class is to have actual values be
+passed between tasks (this is not implemente as the tasks are in the same class and can interchange
+values using the class variable).  The self._state is the name of the task where the plugin is
+at a certain moment.  The self._state variable is of no real use to the plugin developer as he
+must know in what task the plugin is in.
 
 .IP "6. get_plugin()"
 Each plugin must define a get_plugin function.  This function must return the main class of the 
@@ -96,9 +114,34 @@ and the system cannot end in some indeterminate state.
 A plugin for the FirstAidKit must inherit from the pyfirstaidkit.Plugin class. It must also implement 
 the mandatory plugin steps.  The pyfirstaidkit.Plugin parent will provide a default flow that will use 
 the functions defined by the plugin developer.  Moreover, for the mandatory steps, the plugin developer 
-must guarantee that the function will return a valid return  class (more on return class further on).  
+must guarantee that the function will return a valid return  class (see "Return Values section").  
 In other words, the function must return one of the possible return classes included in the default 
-flow.
+flow.  Each plugin must have the get_plugin method in order to actually be seen by the firstaidkit
+backend.
+
+.SH "Class Attributes:"
+This is how the diagnose and fix flows are coded in the backend plugin system.
+ flows["diagnose"] = Flow({
+   initial      : {Return: "prepare"},
+   "prepare"    : {ReturnSuccess: "diagnose"},
+   "diagnose"   : {ReturnSuccess: "clean", ReturnFailure: "clean"},
+   "clean"      : {ReturnSuccess: final, ReturnFailure: final}
+   }, description="The default, fully automated, diagnose sequence")
+
+ flows["fix"] = Flow({
+   initial      : {Return: "prepare"},
+   "prepare"    : {ReturnSuccess: "diagnose"},
+   "diagnose"   : {ReturnSuccess: "clean", ReturnFailure: "backup"},
+   "backup"     : {ReturnSuccess: "fix", ReturnFailure: "clean"},
+   "fix"        : {ReturnSuccess: "clean", ReturnFailure: "restore"},
+   "restore"    : {ReturnSuccess: "clean", ReturnFailure: "clean"},
+   "clean"      : {ReturnSuccess: final, ReturnFailure: final}
+   }, description="The default, fully automated, fixing sequence")
+
+Other important class attributes are: name, version, author and description.  They are selfexplanatory.
+
+
+.SH "Class Methods:"
 pyfirstaidkit.Plugin defines:
 .IP "nextstep()" 
 This is used to return the next function that should be executed.  __iter__() is not used because there 
@@ -153,7 +196,7 @@ returned.
 
 .IP "Adding a flow (Example 3):"
 class MyPlugin(Plugin):
-    flows = Flow.init(Plugin)
+    flows = {}
     flows["myflow"] = Flow({flow rules}, description="")
 
 .SH "SEE ALSO"