firstaidkit-backup.1:

    Update documentation to refer to persistent backups.

1 files changed, 39 insertions, 1 deletions

diff --git a/doc/firstaidkit-backup.1 b/doc/firstaidkit-backup.1
index f75191b..00184ff 100644
--- a/doc/firstaidkit-backup.1
+++ b/doc/firstaidkit-backup.1
@@ -12,7 +12,7 @@ so the developer does not have to care about locks and synchronization.
 
 .SH "Requesting a backup storage space"
 
-Every plugin has access to self.backups attribute, which is the reference
+Every plugin has access to self._backups attribute, which is the reference
 to master backup system instance. Using this attribute to obtain dedicated
 backup space for the plugin is easy. Just type:
 
@@ -49,6 +49,44 @@ Delete backup object with specified name.
 .IP "cleanup(self)"
 Cleanup the backup storage space. You shouldn't use this method, the backup system takes care about it.
 
+.SH "Persistent backup storage space"
+The idea to have a backup space is to use it when the plugin is running or to
+have it when firstaidkit has an unrecoverable error and must bail.  But when
+all went well, firstaidkit deleted all the backups.  The question arose of what
+to do when the user wanted to revert the changes to whatever the plugins had
+done to the system.  This had to be possible, specially with plugins like grub
+that have the potential of making the system unbootable.  The answer to this
+question came in the form of the persistent backups.
+
+.IP "Specifying persistent storage"
+
+A persistent backup will not be deleted at the end of the plugin execution.
+It will persiste in the storage directory untill the user decides to delte
+it.  Firstaidkit will tell the user the dir name when it ends execution.
+To use a persistent the developer must specify when calling the backup space
+that it must be persistent.  This is done by passing persistent=True when
+creating the object.
+
+.IP "Naming persistent storage"
+For the revert feature to work the backup directory must be named in a
+unique form.  This is necesarry to correctly identify the backup dir related to
+the plugin when doing a revert.  You can use the plugin module name for this.
+Not the complete module name, because the preceding submodules before the
+actuall plugin module name might change between pytho virtual machine calls.
+To accomplish this, pass "self.__module__.split('.')[-1:][0]" as the first
+argument of getBackup() call.
+
+If you think that the latter is a little bit too much black magic for you,
+you can also name the backup storage with a string of your preference.  But
+you must implement a function called getBackupId().  This function will return
+the name that you gave the persistent backup storage.  In other words, this
+will return whatever you passed to getBackup()
+
+.IP "Additional info"
+For the persistent backup storage to be used, the developer must add a revert
+function to the plugin.  This is the function that will be called when the
+persistent backup storage is used.
+
 .PP
 
 .SH "Developing another backup storage backend"