From: Richard Russon Date: Wed, 17 Feb 2016 15:50:39 +0000 (+0000) Subject: add docs X-Git-Tag: neomutt-20160530~10^2~9 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=0d49bbc43457257c0d7a448f8d0f01af58a391ea;p=neomutt add docs --- diff --git a/README.compress b/README.compress new file mode 100644 index 000000000..ffddc2cfc --- /dev/null +++ b/README.compress @@ -0,0 +1,165 @@ +Compressed Folders Patch +======================== + + Read from/write to compressed mailboxes + +Patch +----- + + To check if Mutt supports "Compress Folders", look for "+USE_COMPRESSED" in + the mutt version. + + Dependencies + * mutt-1.5.24 + +Introduction +------------ + + The Compressed Folder patch allows Mutt to read mailbox files that are + compressed. But it isn't limited to compressed files. It works well with + encrypted files, too. In fact, if you can create a program/script to + convert to and from your format, then Mutt can read it. + + The patch adds three hooks to Mutt: 'open-hook', 'close-hook' and + 'append-hook'. They define commands to: uncompress a file; compress a file; + append messages to an already compressed file. + + There are some examples of both compressed and encrypted files, later. For + now, the documentation will just concentrate on compressed files. + +Commands +-------- + + open-hook pattern shell-command + close-hook pattern shell-command + append-hook pattern shell-command + + The shell-command must contain two placeholders for filenames: '%f' and + '%t'. These represent "from" and "to" filenames. It's a good idea to put + quotes around these placeholders. + + If you need the exact string "%f" or "%t" in your command, simply double up + the "%" character, e.g. "%%f" or "%%t". + + Not all Hooks are Required + + | Open | Close | Append | Effect | Useful if | + |------|-------|--------|---------------------------------------------|-------------------------------------------------| + | Open | - | - | Folder is readonly | Folder is just a backup | + | Open | Close | - | Folder is read/write, but the entire folder | Compression format doesn't support appending | + | | | | must be written if anything is changed | Compression format doesn't support appending | + | Open | Close | Append | Folder is read/write and emails can be | Compression format supports appending | + | | | | efficiently added to the end | Compression format supports appending | + | Open | - | Append | Folder is readonly, but can be appended to | You want to store emails, but never change them | + + > Note + > + > The command: + > - should return a non-zero exit status on failure + > - should not delete any files + +### Read from compressed mailbox + + open-hook regexp shell-command + + If Mutt is unable to open a file, it then looks for 'open-hook' that + matches the filename. + + If your compression program doesn't have a well-defined extension, then you + can use '.' as the regexp. + +#### Example of open-hook + + open-hook '.gz$' "gzip -cd '%f' > '%t'" + + * Mutt finds a file, "example.gz", that it can't read + * Mutt has an 'open-hook' whose regexp matches the filename: '.gz$' + * Mutt uses the command 'gzip -cd' to create a temporary file that it *can* + read + +### Write to a compressed mailbox + + close-hook regexp shell-command + + When Mutt has finished with a compressed mail folder, it will look for a + matching 'close-hook' to recompress the file. This hook is optional. + + > Note + > + > If the folder has not been modifed, the + > close-hook + > will not be called. + +#### Example of close-hook + + close-hook '.gz$' "gzip -c '%t' > '%f'" + + * Mutt has finished with a folder, "example.gz", that it opened with + 'open-hook' + * The folder has been modified + * Mutt has a 'close-hook' whose regexp matches the filename: '.gz$' + * Mutt uses the command 'gzip -c' to create a new compressed file + +### Append to a compressed mailbox + + append-hook regexp shell-command + + When Mutt wants to append an email to a compressed mail folder, it will + look for a matching 'append-hook'. This hook is optional. + + Using the 'append-hook' will save time, but Mutt won't be able to determine + the type of the mail folder inside the compressed file. + + Mutt will *assume* the type to be that of the '$mbox_type' variable. Mutt + also uses this type for temporary files. + + Mutt will only use the 'append-hook' for existing files. The 'close-hook' + will be used for empty, or missing files. + +#### Example of append-hook + + append-hook '.gz$' "gzip -c '%t' >> '%f'" + + * Mutt wants to append an email to a folder, "example.gz", that it opened + with 'open-hook' + * Mutt has an 'append-hook' whose regexp matches the filename: '.gz$' + * Mutt knows the mailbox type from the '$mbox' variable + * Mutt uses the command 'gzip -c' to append to an existing compressed file + +### Empty Files + + Mutt assumes that an empty file is not compressed. In this situation, unset + $save_empty, so that the compressed file will be removed if you delete all + of the messages. + +### Security + + Encrypted files are decrypted into temporary files which are stored in the + $tmpdir directory. This could be a security risk. + +See Also +-------- + + * NeoMutt project + * Compile-Time Features + * Regular Expressions + * $tmpdir + * $mbox_type + * $save_empty + * folder-hook + +Known Bugs +---------- + + * The Compressed Folder hooks cannot deal with filenames that contains + quotes/apostrophes. + +Credits +------- + + * Roland Rosenfeld + * Alain Penders + * Christoph "Myon" Berg + * Evgeni Golov + * Richard Russon + diff --git a/doc/Makefile.am b/doc/Makefile.am index bc8f856d7..6021626f3 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -37,7 +37,8 @@ EXTRA_DIST = dotlock.man \ CHUNKED_DOCFILES = index.html intro.html gettingstarted.html \ configuration.html mimesupport.html advancedusage.html \ - optionalfeatures.html security.html tuning.html reference.html miscellany.html + optionalfeatures.html security.html tuning.html reference.html miscellany.html \ + compressed-folders.html HTML_DOCFILES = manual.html $(CHUNKED_DOCFILES) diff --git a/doc/manual.xml.head b/doc/manual.xml.head index 5b72b3384..56430f013 100644 --- a/doc/manual.xml.head +++ b/doc/manual.xml.head @@ -5519,12 +5519,24 @@ option/command. See: + + +append-hook + + + charset-hook + + +close-hook + + + crypt-hook @@ -5567,6 +5579,12 @@ option/command. See: + + +open-hook + + + reply-hook @@ -6261,205 +6279,6 @@ selection. Highest priority has the mailbox given with the - -Compressed folders Support (OPTIONAL) - - -If Mutt was compiled with compressed folders support (by running the -configure script with the ---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 (open-hook, close-hook and append-hook) which define commands to -uncompress and compress a folder and to append messages to an existing -compressed folder respectively. - -For example: - - -open-hook \\.gz$ "gzip -cd %f > %t" -close-hook \\.gz$ "gzip -c %t > %f" -append-hook \\.gz$ "gzip -c %t >> %f" - - -You do not have to specify all of the commands. If you omit append-hook, the folder will be open and -closed again each time you will add to it. If you omit close-hook (or give empty command) , the -folder will be open in the mode. If you specify 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 -"." as a regexp. But this may be surprising if your -compressing script produces empty files. In this situation, unset -$save_empty, so that -the compressed file will be removed if you delete all of the messages. - - - -Open a compressed mailbox for reading - - -Usage: open-hook regexp "command" - -The command is the command that can be used for -opening the folders whose names match regexp. - -The command string is the printf-like format -string, and it should accept two parameters: %f, which is -replaced with the (compressed) folder name, and %t which is -replaced with the name of the temporary folder to which to write. - -%f and %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, %% is replaced by -%, as in printf, and any other %anything is left as is. - -The command should not remove the original compressed file. The -command should return non-zero exit status if it -fails, so mutt knows something's wrong. - -Example: - - -open-hook \\.gz$ "gzip -cd %f > %t" - - -If the command is empty, this operation is -disabled for this file type. - - - - -Write a compressed mailbox - - -Usage: close-hook regexp "command" - -This is used to close the folder that was open with the open-hook command after some changes were -made to it. - -The command string is the command that can be -used for closing the folders whose names match -regexp. It has the same format as in the open-hook command. Temporary folder in this -case is the folder previously produced by the open-hook command. - -The command should not remove the decompressed file. The -command should return non-zero exit status if it -fails, so mutt knows something's wrong. - -Example: - - -close-hook \\.gz$ "gzip -c %t > %f" - - -If the command is empty, this operation is -disabled for this file type, and the file can only be open in the -read-only mode. - -close-hook is not called when you -exit from the folder if the folder was not changed. - - - - -Append a message to a compressed mailbox - - -Usage: append-hook regexp "command" - -This command is used for saving to an existing compressed folder. The -command is the command that can be used for -appending to the folders whose names match -regexp. It has the same format as in the open-hook command. The temporary folder in -this case contains the messages that are being appended. - -The command should not remove the decompressed file. The -command should return non-zero exit status if it -fails, so mutt knows something's wrong. - -Example: - - -append-hook \\.gz$ "gzip -c %t >> %f" - - -When 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 ($mbox_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, close-hook is called, and not append-hook. append-hook is only for appending to -existing folders. - -If the command is empty, this operation is -disabled for this file type. In this case, the folder will be open and -closed again (using open-hook and -close-hookrespectively) each time you -will add to it. - - - - -Encrypted folders - - -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: - - -open-hook \\.pgp$ "pgp -f < %f > %t" -close-hook \\.pgp$ "pgp -fe YourPgpUserIdOrKeyId < %t > %f" - - -Please note, that PGP does not support appending to an encrypted -folder, so there is no append-hook defined. - -If you are using GnuPG instead of PGP, you may use the following hooks -instead: - - -open-hook \\.gpg$ "gpg --decrypt < %f > %t" -close-hook \\.gpg$ "gpg --encrypt --recipient YourGpgUserIdOrKeyId < %t > %f" - - -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. - - - - Mutt's MIME Support @@ -8280,6 +8099,383 @@ please have a look at the mixmaster documentation. + + Compressed Folders Patch + Read from/write to compressed mailboxes + + + Patch + + + To check if Mutt supports Compress Folders, look for + +USE_COMPRESSED in the mutt version. + See: . + + + + Dependencies: + mutt-1.5.24 + + + This patch is part of the NeoMutt Project. + + + + Introduction + + + The Compressed Folder patch allows Mutt to read mailbox files that are + compressed. But it isn't limited to compressed files. It works well + with encrypted files, too. In fact, if you can create a program/script + to convert to and from your format, then Mutt can read it. + + + + The patch adds three hooks to Mutt: open-hook, + close-hook and append-hook. They + define commands to: uncompress a file; compress a file; append + messages to an already compressed file. + + + + There are some examples of both compressed and encrypted files, + later. For now, the documentation will just concentrate on + compressed files. + + + + + + + + Commands + + open-hook + + pattern + + + shell-command + + close-hook + + pattern + + + shell-command + + append-hook + + pattern + + + shell-command + + + + + The shell-command must contain two placeholders for filenames: + %f and %t. These represent + from and to filenames. It's a good idea to + put quotes around these placeholders. + + + + If you need the exact string %f or %t in your + command, simply double up the % character, e.g. + %%f or %%t. + + + + Not all Hooks are Required + + + + Open + Close + Append + Effect + Useful if + + + + + Open + - + - + Folder is readonly + The folder is just a backup + + + Open + Close + - + Folder is read/write, but the entire folder must be + written if anything is changed + Your compression format doesn't support appending + + + Open + Close + Append + Folder is read/write and emails can be efficiently added + to the end + Your compression format supports appending + + + Open + - + Append + Folder is readonly, but can be appended to + You want to store emails, but never change them + + + +
+ + + The command: + + should return a non-zero exit status on failure + should not delete any files + + + + + Read from compressed mailbox + + open-hook regexp shell-command + + + If Mutt is unable to open a file, it then looks for + open-hook that matches the filename. + + + + If your compression program doesn't have a well-defined extension, + then you can use . as the regexp. + + + + Example of open-hook + + open-hook '\.gz$' "gzip -cd '%f' > '%t'" + + + Mutt finds a file, example.gz, + that it can't read + Mutt has an open-hook + whose regexp matches the filename: + \.gz$ + Mutt uses the command gzip -cd + to create a temporary file that it can + read + + + + + + Write to a compressed mailbox + + close-hook regexp shell-command + + + When Mutt has finished with a compressed mail folder, it will look + for a matching close-hook to recompress the file. + This hook is optional. + + + + If the folder has not been modifed, the + close-hook will not be called. + + + + Example of close-hook + + close-hook '\.gz$' "gzip -c '%t' > '%f'" + + + Mutt has finished with a folder, example.gz, + that it opened with open-hook + The folder has been modified + Mutt has a close-hook whose regexp + matches the filename: \.gz$ + Mutt uses the command gzip -c + to create a new compressed file + + + + + + Append to a compressed mailbox + + append-hook regexp shell-command + + + When Mutt wants to append an email to a compressed mail folder, it + will look for a matching append-hook. + This hook is optional. + + + + Using the append-hook will save time, but + Mutt won't be able to determine the type of the mail folder + inside the compressed file. + + + + Mutt will assume the type to be that of + the $mbox_type variable. Mutt also uses + this type for temporary files. + + + + Mutt will only use the append-hook for existing files. + The close-hook will be used for empty, or missing files. + + + + Example of append-hook + + append-hook '\.gz$' "gzip -c '%t' >> '%f'" + + + Mutt wants to append an email to a folder, example.gz, + that it opened with open-hook + Mutt has an append-hook whose regexp matches + the filename: \.gz$ + Mutt knows the mailbox type from the $mbox + variable + Mutt uses the command gzip -c + to append to an existing compressed file + + + + + + + Empty Files + + + Mutt assumes that an empty file is not compressed. In this + situation, unset $save_empty, so + that the compressed file will be removed if you delete all of the + messages. + + + + + Security + + + Encrypted files are decrypted into temporary files which are + stored in the $tmpdir directory. + This could be a security risk. + + + + + + + + Muttrc + +# Example Mutt config file for the 'compressed folders' feature. + +# This feature adds three hooks to Mutt which allow it to +# work with compressed, or encrypted, mailboxes. + +# The hooks are of the form: +# open-hook regexp "shell-command" +# close-hook regexp "shell-command" +# append-hook regexp "shell-command" + +# The 'append-hook' is optional. + +# Hander for gzip compressed mailboxes +open-hook '\.gz$' "gzip -cd '%f' > '%t'" +close-hook '\.gz$' "gzip -c '%t' > '%f'" +append-hook '\.gz$' "gzip -c '%t' >> '%f'" + +# Hander for bzip2 compressed mailboxes +open-hook '\.bz2$' "bzip2 -cd '%f' > '%t'" +close-hook '\.bz2$' "bzip2 -c '%t' > '%f'" +append-hook '\.bz2$' "bzip2 -c '%t' >> '%f'" + +# Hander for xz compressed mailboxes +open-hook '\.xz$' "xz -cd '%f' > '%t'" +close-hook '\.xz$' "xz -c '%t' > '%f'" +append-hook '\.xz$' "xz -c '%t' >> '%f'" + +# Hander for pgp encrypted mailboxes +# PGP does not support appending to an encrypted file +open-hook '\.pgp$' "pgp -f < '%f' > '%t'" +close-hook '\.pgp$' "pgp -fe YourPgpUserIdOrKeyId < '%t' > '%f'" + +# Hander for gpg encrypted mailboxes +# gpg does not support appending to an encrypted file +open-hook '\.gpg$' "gpg --decrypt < '%f' > '%t'" +close-hook '\.gpg$' "gpg --encrypt --recipient YourGpgUserIdOrKeyId < '%t' > '%f'" + +# vim: syntax=muttrc + + + + + See Also + + + NeoMutt Project + Compile-Time Features + Regular Expressions + $tmpdir + $mbox_type + $save_empty + folder-hook + + + + + Known Bugs + + + The Compressed Folder hooks cannot deal with filenames that contains quotes/apostrophes. + + + + + Credits + + Roland Rosenfeld roland@spinnaker.de + Alain Penders Alain@Finale-Dev.com + Christoph Myon Berg myon@debian.org + Evgeni Golov evgeni@debian.org + Richard Russon rich@flatcap.org + + + + @@ -8820,6 +9016,18 @@ The following are the commands understood by Mutt: + + +append-hook + +pattern + + +shell-command + + + + auto_view @@ -8881,6 +9089,18 @@ The following are the commands understood by Mutt: + + +close-hook + +pattern + + +shell-command + + + + color @@ -8950,6 +9170,18 @@ The following are the commands understood by Mutt: + + +open-hook + +pattern + + +shell-command + + + + crypt-hook diff --git a/doc/muttrc.compress b/doc/muttrc.compress new file mode 100644 index 000000000..ab6fe3c84 --- /dev/null +++ b/doc/muttrc.compress @@ -0,0 +1,38 @@ +# Example Mutt config file for the 'compressed folders' feature. + +# This feature adds three hooks to Mutt which allow it to +# work with compressed, or encrypted, mailboxes. + +# The hooks are of the form: +# open-hook regexp "shell-command" +# close-hook regexp "shell-command" +# append-hook regexp "shell-command" + +# The 'append-hook' is optional. + +# Hander for gzip compressed mailboxes +open-hook '\.gz$' "gzip -cd '%f' > '%t'" +close-hook '\.gz$' "gzip -c '%t' > '%f'" +append-hook '\.gz$' "gzip -c '%t' >> '%f'" + +# Hander for bzip2 compressed mailboxes +open-hook '\.bz2$' "bzip2 -cd '%f' > '%t'" +close-hook '\.bz2$' "bzip2 -c '%t' > '%f'" +append-hook '\.bz2$' "bzip2 -c '%t' >> '%f'" + +# Hander for xz compressed mailboxes +open-hook '\.xz$' "xz -cd '%f' > '%t'" +close-hook '\.xz$' "xz -c '%t' > '%f'" +append-hook '\.xz$' "xz -c '%t' >> '%f'" + +# Hander for pgp encrypted mailboxes +# PGP does not support appending to an encrypted file +open-hook '\.pgp$' "pgp -f < '%f' > '%t'" +close-hook '\.pgp$' "pgp -fe YourPgpUserIdOrKeyId < '%t' > '%f'" + +# Hander for gpg encrypted mailboxes +# gpg does not support appending to an encrypted file +open-hook '\.gpg$' "gpg --decrypt < '%f' > '%t'" +close-hook '\.gpg$' "gpg --encrypt --recipient YourGpgUserIdOrKeyId < '%t' > '%f'" + +# vim: syntax=muttrc diff --git a/doc/muttrc.man.head b/doc/muttrc.man.head index 4ecce35b7..6ab69a704 100644 --- a/doc/muttrc.man.head +++ b/doc/muttrc.man.head @@ -358,24 +358,24 @@ You may use multiple \fBcrypt-hook\fPs with the same \fIregexp\fP; multiple matching \fBcrypt-hook\fPs result in the use of multiple \fIkey-id\fPs for a recipient. -+.PP -+.nf -+\fBopen-hook\fP \fIregexp\fP "\fIcommand\fP" -+\fBclose-hook\fP \fIregexp\fP "\fIcommand\fP" -+\fBappend-hook\fP \fIregexp\fP "\fIcommand\fP" -+.fi -+.IP -+These commands provide a way to handle compressed folders. The given -+\fBregexp\fP specifies which folders are taken as compressed (e.g. -+"\fI\\\\.gz$\fP"). The commands tell Mutt how to uncompress a folder -+(\fBopen-hook\fP), compress a folder (\fBclose-hook\fP) or append a -+compressed mail to a compressed folder (\fBappend-hook\fP). The -+\fIcommand\fP string is the -+.BR printf (3) -+like format string, and it should accept two parameters: \fB%f\fP, -+which is replaced with the (compressed) folder name, and \fB%t\fP -+which is replaced with the name of the temporary folder to which to -+write. +.PP +.nf +\fBopen-hook\fP \fIregexp\fP "\fIcommand\fP" +\fBclose-hook\fP \fIregexp\fP "\fIcommand\fP" +\fBappend-hook\fP \fIregexp\fP "\fIcommand\fP" +.fi +.IP +These commands provide a way to handle compressed folders. The given +\fBregexp\fP specifies which folders are taken as compressed (e.g. +"\fI\\\\.gz$\fP"). The commands tell Mutt how to uncompress a folder +(\fBopen-hook\fP), compress a folder (\fBclose-hook\fP) or append a +compressed mail to a compressed folder (\fBappend-hook\fP). The +\fIcommand\fP string is the +.BR printf (3) +like format string, and it should accept two parameters: \fB%f\fP, +which is replaced with the (compressed) folder name, and \fB%t\fP +which is replaced with the name of the temporary folder to which to +write. .TP \fBpush\fP \fIstring\fP This command adds the named \fIstring\fP to the keyboard buffer. diff --git a/doc/vimrc-compress b/doc/vimrc-compress new file mode 100644 index 000000000..e84fad281 --- /dev/null +++ b/doc/vimrc-compress @@ -0,0 +1,7 @@ +" Vim syntax file for the mutt compress patch + +syntax keyword muttrcCommand append-hook +syntax keyword muttrcCommand close-hook +syntax keyword muttrcCommand open-hook + +" vim: syntax=vim