X-Git-Url: http://git.madism.org/?a=blobdiff_plain;f=doc%2Fmanual.sgml.head;h=556cff8b01f9bb819aa5775785374c9e03af8cf1;hb=6e0187ce721be4997bef32d724528f8976df89d6;hp=8ad8d3bc444d3f3c92c46872725ab5963cc8b527;hpb=6833ce8bdca2d64e14485118f2a4417b7e1cb1b1;p=apps%2Fmadmutt.git

diff --git a/doc/manual.sgml.head b/doc/manual.sgml.head
index 8ad8d3b..556cff8 100644
--- a/doc/manual.sgml.head
+++ b/doc/manual.sgml.head
@@ -2412,6 +2412,168 @@ macro index \cb |urlview\n
 macro pager \cb |urlview\n
 </verb></tscreen>
 
+<sect1>Compressed folders Support (OPTIONAL)
+<p>
+
+If Mutt was compiled with compressed folders support (by running the
+<em/configure/ script with the <em/--enable-compressed/ flag), Mutt
+can open folders stored in an arbitrary format, provided that the user
+has a script to convert from/to this format to one of the accepted.
+
+The most common use is to open compressed archived folders e.g. with
+gzip.
+
+In addition, the user can provide a script that gets a folder in an
+accepted format and appends its context to the folder in the
+user-defined format, which may be faster than converting the entire
+folder to the accepted format, appending to it and converting back to
+the user-defined format.
+
+There are three hooks defined (<ref id="open-hook" name="open-hook">,
+<ref id="close-hook" name="close-hook"> and <ref id="append-hook"
+name="append-hook">) which define commands to uncompress and compress
+a folder and to append messages to an existing compressed folder 
+respectively.
+
+For example:
+
+<tscreen><verb>
+open-hook \\.gz$ "gzip -cd %f > %t" 
+close-hook \\.gz$ "gzip -c %t > %f"
+append-hook \\.gz$ "gzip -c %t >> %f" 
+</verb></tscreen>
+
+You do not have to specify all of the commands. If you omit <ref
+id="append-hook" name="append-hook">, the folder will be open and
+closed again each time you will add to it. If you omit <ref
+id="close-hook" name="close-hook"> (or give empty command) , the
+folder will be open in the  mode. If you specify <ref
+id="append-hook" name="append-hook"> though you'll be able to append
+to the folder.
+
+Note that Mutt will only try to use hooks if the file is not in one of
+the accepted formats. In particular, if the file is empty, mutt
+supposes it is not compressed. This is important because it allows the
+use of programs that do not have well defined extensions. Just use
+&dquot;.&dquot; as a regexp. But this may be surprising if your
+compressing script produces empty files. In this situation, unset <ref
+id="save_empty" name="&dollar;save&lowbar;empty">, so that the compressed file
+will be removed if you delete all of the messages.
+
+<sect2>Open a compressed mailbox for reading<label id="open-hook">
+<p>
+Usage: <tt/open-hook/ <em/regexp/ &dquot;<em/command/&dquot;
+
+The <em/command/ is the command that can be used for opening the
+folders whose names match <em/regexp/.
+
+The <em/command/ string is the printf-like format string, and it
+should accept two parameters: &percnt;f, which is replaced with the
+(compressed) folder name, and &percnt;t which is replaced with the
+name of the temporary folder to which to write.
+
+&percnt;f and &percnt;t can be repeated any number of times in the
+command string, and all of the entries are replaced with the
+appropriate folder name. In addition, &percnt;&percnt; is replaced by
+&percnt;, as in printf, and any other &percnt;anything is left as is.
+
+The <em/command/ should <bf/not/ remove the original compressed file.
+The <em/command/ should return non-zero exit status if it fails, so
+mutt knows something's wrong.
+
+Example:
+
+<tscreen><verb>
+open-hook \\.gz$ "gzip -cd %f > %t" 
+</verb></tscreen>
+
+If the <em/command/ is empty, this operation is disabled for this file
+type.
+
+<sect2>Write a compressed mailbox<label id="close-hook">
+<p>
+Usage: <tt/close-hook/ <em/regexp/ &dquot;<em/command/&dquot;
+
+This is used to close the folder that was open with the <ref id="open-hook" 
+name="open-hook"> command after some changes were made to it.
+
+The <em/command/ string is the command that can be used for closing the
+folders whose names match <em/regexp/. It has the same format as in 
+the <ref id="open-hook" name="open-hook"> command. Temporary folder
+in this case is the folder previously produced by the <<ref id="open-hook"
+name="open-hook"> command.
+
+The <em/command/ should <bf/not/ remove the decompressed file. The
+<em/command/ should return non-zero exit status if it fails, so mutt
+knows something's wrong.
+
+Example:
+
+<tscreen><verb>
+close-hook \\.gz$ "gzip -c %t > %f"
+</verb></tscreen>
+
+If the <em/command/ is empty, this operation is disabled for this file
+type, and the file can only be open in the readonly mode.
+
+<ref id="close-hook" name ="close-hook"> is not called when you exit
+from the folder if the folder was not changed.
+
+<sect2>Append a message to a compressed mailbox<label id="append-hook">
+<p>
+Usage: <tt/append-hook/ <em/regexp/ &dquot;<em/command/&dquot;
+
+This command is used for saving to an existing compressed folder.
+The <em/command/ is the command that can be used for appending to the
+folders whose names match <em/regexp/. It has the same format as in 
+ the <ref id="open-hook" name="open-hook"> command.
+The temporary folder in this case contains the messages that are being
+appended. 
+
+The <em/command/ should <bf/not/ remove the decompressed file. The
+<em/command/ should return non-zero exit status if it fails, so mutt
+knows something's wrong.
+
+Example:
+
+<tscreen><verb>
+append-hook \\.gz$ "gzip -c %t >> %f" 
+</verb></tscreen>
+
+When <ref id="append-hook" name="append-hook"> is used, the folder is
+not opened, which saves time, but this means that we can not find out
+what the folder type is. Thus the default (<ref id="mbox_type"
+name="&dollar;mbox&lowbar;type">) type is always supposed (i.e.
+this is the format used for the temporary folder).
+
+If the file does not exist when you save to it, <ref id="close-hook"
+name="close-hook"> is called, and not <ref id="append-hook"
+name="append-hook">. <ref id="append-hook" name="append-hook"> is only
+for appending to existing folders.
+
+If the <em/command/ is empty, this operation is disabled for this file
+type. In this case, the folder will be open and closed again (using
+<ref id="open-hook" name="open-hook"> and <ref id="close-hook" 
+name="close-hook">respectively) each time you will add to it.
+
+<sect2>Encrypted folders
+<p>
+The compressed folders support can also be used to handle encrypted
+folders. If you want to encrypt a folder with PGP, you may want to use
+the following hooks:
+
+<tscreen><verb>
+open-hook  \\.pgp$ "pgp -f < %f > %t"
+close-hook \\.pgp$ "pgp -fe YourPgpUserIdOrKeyId < %t > %f"
+</verb></tscreen>
+
+Please note, that PGP does not support appending to an encrypted
+folder, so there is no append-hook defined.
+
+<bf/Note:/ the folder is temporary stored decrypted in the /tmp
+directory, where it can be read by your system administrator. So think
+about the security aspects of this.
+
 <sect>Mutt's MIME Support
 <p>
 Quite a bit of effort has been made to make Mutt the premier text-mode
@@ -2991,6 +3153,8 @@ The following are the commands understood by mutt.
 <item>
 <tt><ref id="alternative_order" name="unalternative&lowbar;order"></tt> <em/mimetype/ &lsqb; <em/mimetype/ ... &rsqb;
 <item>
+<tt><ref id="append-hook" name="append-hook"></tt> <em/regexp/ <em/command/
+<item>
 <tt><ref id="auto_view" name="auto&lowbar;view"></tt> <em/mimetype/ &lsqb; <em/mimetype/ ... &rsqb;
 <item>
 <tt><ref id="auto_view" name="unauto&lowbar;view"></tt> <em/mimetype/ &lsqb; <em/mimetype/ ... &rsqb;
@@ -2999,6 +3163,8 @@ The following are the commands understood by mutt.
 <item>
 <tt><ref id="charset-hook" name="charset-hook"></tt> <em/alias/ <em/charset/
 <item>
+<tt><ref id="close-hook" name="close-hook"></tt> <em/regexp/ <em/command/
+<item>
 <tt><ref id="color" name="color"></tt> <em/object/ <em/foreground/ <em/background/ &lsqb; <em/regexp/ &rsqb;
 <item>
 <tt><ref id="color" name="uncolor"></tt> <em/index/ <em/pattern/ &lsqb; <em/pattern/ ... &rsqb;
@@ -3045,6 +3211,8 @@ The following are the commands understood by mutt.
 <item>
 <tt><ref id="my_hdr" name="unmy&lowbar;hdr"></tt> <em/field/ &lsqb; <em/field/ ... &rsqb;
 <item>
+<tt><ref id="open-hook" name="open-hook"></tt> <em/regexp/ <em/command/
+<item>
 <tt><ref id="crypt-hook" name="crypt-hook"></tt> <em/pattern/ <em/key-id/
 <item>
 <tt><ref id="push" name="push"></tt> <em/string/