Correct stuff in the fakplugin.1 file.

Increase readability in our docs :)

1 files changed, 105 insertions, 78 deletions

diff --git a/doc/fakplugin.1 b/doc/fakplugin.1
index c110307..ca1d958 100644
--- a/doc/fakplugin.1
+++ b/doc/fakplugin.1
@@ -2,101 +2,108 @@
 .SH "NAME" firstaidkit-plugins
 .BR
 .SH "DESCRIPTION"
-Here is a descriptions of the plugin model used in firstaidkit and how to work with it.
+This man page tries to describe the inner workings of the plugin system for FirstAidKit. 
+It also contains useful information to develop a plugin for firstaidkit.
 
-.SH "Plugin Sufixes"
-All plugins belong to configured plugin directory. Recognized suffixes are: .py, .pyc, .pyo (python modules) and .so (python compatible binary module)
+.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).
+.\"Should mention the /etc/firstaidkit.conf file.  Should include multiple plugin source dirs.\"
 
 .SH "Plugin Model"
-The building blocks of the plugins are functions and flows.  A function is a certain action that is taken inside the plugin.  This action is more or less independant 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.
-
-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.  This order/flow is specified using the function  names, their return codes and the flow structure.  All this is contained within a dictionary.
-
-.IP
-Example 1:
-Consider the following flow:
-    start->fix->end
-The dictionary that expresses this flow:
-    dict = { start:fix, fix:end}
-
-Example 2:
-Consider the following flow:
-                  ,>end
-    start->diagnose
-                  `>fix->end
-
-This flow has a conditional after the diagnose function.  If diagnose results in a corrupt state of the system, then the plugin proceeds  with fix.  If all is good in the system, then the flow end.
-The dictionary that expresses this flow: dict = {start:diagnose, diagnose:{"goodSys":end, "badSys":fix}, fix:end} note that the next step in the diagnose case is defined buy whatever diagnose returned.
-.PP
-
-The idea is to define individual set of activities in the functions.  And to put these activities together with the flows.  As mentioned before the activities are just functions.  The flow on the other hand is a dict that defines the next function to execute given the return value of the current function.
-
-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 necesary to correclty execute the flow given by the flow dictionary.
+The building blocks of the plugins are functions and flows.  A function is a certain action 
+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.
+
+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 
+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 
+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 used to describe the plugin and are used without actually using a instance of the plugin.  This is important because we do not want to execute the __init__ fucntion and cause lots of unnecesary  stuff to go into memory when we are querying for plugin basic information.
+The main plugin class has some class methods and some class attributes. These elements are 
+used to describe the plugin and are used without actually using a instance of the plugin.  
+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, 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: 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).
-.PP
+The class attributes 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).
 
 .IP "2. Plugin dependencies"
-You can also specify flags, which are required to be satisfied before the automated mode can use this plugin. The requirements should be returned as python set of strings by the getDeps() class method.
-
-Setting flags is also easy. Just use the provide() method common to all plugins.
+You can also specify flags, which are required to be satisfied before the automated mode can 
+use this plugin. The requirements should be returned as python set of strings by the getDeps() 
+class method.  Setting flags is also easy. Just use the provide() method common to all plugins.
 
 .IP "3. Default functions:"
 See section "Common stuff for plugins"
-.PP
 
 .IP "4. Flows:"
-If you want to redefine or add your own flows into your plugin, the first step to do is to init the flow system like this:
-
- class MyPlugin(Plugin):
-  flows = Flow.init(Plugin)
-
-Then you add your flow as new keys to the flows dictionary so it will look like this:
-
- class MyPlugin(Plugin):
-  flows = Flow.init(Plugin)
-  flows["myflow"] = Flow({flow rules}, description="")
-.PP
+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.
 
 .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._resutl 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._resutl value.
-.PP
+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.
 
 .IP "6. get_plugin()"
-Each plugin must define a get_plugin function.  This function must return the main class of the plugin.  This is used to take out info from the plugin, and to instantiate it.  If in doubt, take a look at the sample plugins that come with the man FirstAidKit code base. They can give you a prety good idea of what to do when using a  module, file ...
-.PP
+Each plugin must define a get_plugin function.  This function must return the main class of the 
+plugin.  This is used to take out info from the plugin, and to instantiate it.  If in doubt, take a 
+look at the sample plugins that come with the man FirstAidKit code base. They can give you a pretty 
+good idea of what to do when using a  module, file ...
 
 .IP "7. return values:"
-For each function you code in a plugin you must use predefined return classes.  It is necesarry to have the extra wrapper because the python native types can get messy (1==True).  Just use the ones provided by  the plugin system, or create your own.
+For each function you code in a plugin you must use predefined return classes.  It is necessary to 
+have the extra wrapper because the python native types can get messy (1==True).  Just use the ones 
+provided by  the plugin system, or create your own.
 
 .SH "Common stuff"
-Each plugin exports some steps. 
-.IP "The mandatory ones are:"
- \(bu prepare -- initialize plugin, get environment
- \(bubackup -- backup everything we could touch in this plugin
- \(budiagnose -- get info about the investigated system and determine where the problems are
- \(bufix -- autofix the errors from diagnose step
- \(burestore -- restore system from backup
- \(buclean -- destroy the plugin, cleanup
-
+Each plugin, by default, should exports some steps. The mandatory ones are:
+.IP "prepare" 
+Initialize plugin, get environment.
+.IP "backup" 
+Backup everything we could touch in this plugin.
+.IP "diagnose"
+Get info about the investigated system and determine where the problems are.
+.IP "fix" 
+Auto fix the errors from diagnose step.
+.IP "restore" 
+Restore system from backup.
+.IP "clean" 
+Destroy the plugin, cleanup.
+.PP
 The plugin should ensure that the calling order is correct
-and the system cannot end in some undeterministic state.
-
+and the system cannot end in some indeterminate state.
 
 .SH "Python Modules:"
-A plugin for the FirstAidKit must inherite 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 garantee that the function will return a valid return  class (more on return class further on).  In other words, the function must return one of the possible return classes included in the default
+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).  
+In other words, the function must return one of the possible return classes included in the default 
 flow.
 pyfirstaidkit.Plugin defines:
-
 .IP "nextstep()" 
-This is used to return the next function that should be executed.  __iter__() is not used because there is no control over __iter__() in an iteration.  nextstep() allows us execution of the flow without the need for an iteration.  However the iteratior is present in the class and can be used accordinly.
+This is used to return the next function that should be executed.  __iter__() is not used because there 
+is no control over __iter__() in an iteration.  nextstep() allows us execution of the flow without the 
+need for an iteration.  However the iteration is present in the class and can be used accordingly.
 .IP "__iter__() and next()" 
 Iterator protocol, works in the same way as nextstep() but end with StopIteration exception
 .IP "actions()" 
@@ -108,7 +115,8 @@ Returns tuple of strings defined as (name of plugin, version, author)
 .IP "changeFlow()" 
 Allows the caller to change to some other flow defined in the plugin.
 .IP "getFlows()"
-Returns all the possible flows that the plugin suports. And of course the steps itself. They are defined as methods with the same names as used in actions().
+Returns all the possible flows that the plugin supports. And of course the steps itself. They are 
+defined as methods with the same names as used in actions().
 .IP "getDeps()"
 Returns list of flags which are required for this plugin to operate in automated mode.
 .IP "provide(flag)"
@@ -117,24 +125,43 @@ Adds flag into the pool of satisfied flags.
 Queries the state of flag. Returns True if set, False otherwise.
 
 .SH "Arbitrary Executable Modules"
-The current approach is to create a wrapper python plugin, which holds the metadata
-and calls the binaries as neccessary (see the examples).
+The current approach is to create a wrapper python plugin, which holds the meta data
+and calls the binaries as necessary (see the examples).
+
+.SH "Examples"
+.IP "Flow description (Example 1):"
+Consider the following flow and its dictionary:
+    start->fix->end
+    dict = { start:fix, 
+             fix:end
+           }
+
+.IP "Flow description (Example 2):"
+Consider the following flow and its dictionary:
+                   ,>end
+    start->diagnose
+                   `>fix->end
+    dict = { start:diagnose, 
+             diagnose:{"goodSys":end,"badSys":fix}, 
+             fix:end 
+           }
+
+This flow has a conditional after the diagnose function.  If diagnose results in a corrupt 
+state of the system, then the plugin proceeds  with fix.  If all is good in the system, then 
+the flow end.  Note that the next step in the diagnose case is defined buy whatever diagnose 
+returned.
+
+.IP "Adding a flow (Example 3):"
+class MyPlugin(Plugin):
+    flows = Flow.init(Plugin)
+    flows["myflow"] = Flow({flow rules}, description="")
 
-.PP
 .SH "SEE ALSO"
-.nf
 http://fedorahosted.org/firstaidkit
-.fi
 
-.PP
 .SH "AUTHORS"
-.nf
 Martin Sivak <msivak@redhat.com>
 Joel Granados <jgranado@redhat.com>
-.fi
 
-.PP
 .SH "BUGS"
-.nf
 Please search/report bugs at http://fedorahosted.org/firstaidkit/newticket
-.fi