*CheckAttach.txt*  Check attachments when writing mails using mutt

Author:  Christian Brabandt <cb@256bit.org>
Version: 0.17 Thu, 07 Mar 2024 21:01:19 +0100
Copyright: (c) 2009-2013 by Christian Brabandt            *CheckAttach-copyright*
           The VIM LICENSE applies to CheckAttach.vim and CheckAttach.txt
           (see |copyright|) except use CheckAttach instead of "Vim".
           NO WARRANTY, EXPRESS OR IMPLIED.  USE AT-YOUR-OWN-RISK.

=============================================================================
							*CheckAttach-Install*
1. Installation

Simply clone this package inside your package folder: >

    git clone https://github.com/chrisbra/CheckAttach ~/.vim/pack/dist/start/CheckAttach
<
Then, make sure you enable filetype plugins for your Vim. This is done using >

    :filetype plugin on

See |:filetype| for more inforation.

After restarting Vim, the CheckAttach functionality should be available for
all files of tiletype mail |mail.vim| (e.g. when editing files from within
mutt).


                                                                 *CheckAttach*
2. Functionality

When using mutt as your mail user agent, you can specify which files to attach
using the pseudo header :Attach. This only works when edit_headers is set in
your .muttrc configuration file. See the mutt manual for further information
about that topic.

A simple version of this plugin has been posted to the mutt-users list (see
http://marc.info/?i=20090116091203.GB3197%20()%20256bit%20!%20org) and
after using it for some time, I decided to make a plugin out of it.

This plugin checks, whether certain keywords exist in your mail, and if found,
you'll be asked to attach the files. This is done to prevent that you sent
mails in which you announce to attach some files but actually forget to attach
the files so that your have to write a second mail which often is quite
embarrassing.

Therefore this plugin checks for the presence of keywords (but does not
consider the quoted part of the message, that is, any line that does not start
with '>') which indicate that an attachment should be attached. If if finds
these keywords, the plugin will highlight the keywords and ask you for the
files to attach, whenever you save your mail.

This looks like this:
Attach file: (leave empty to abort):

At that prompt you can specify any file you'd like to attach. It allows
filename completion, so you can use <Tab> to let vim complete file paths.
Additionally you can specify glob patterns and let vim attach all files, that
match the pattern. So if you enter ~/.vim/plugin/*.vim vim would add for each
plugin it finds an Attach-header. If you enter an empty value or "n" (without
the quotes), no file will be attached. If you have the plugin configured to
use an external filebrowser (see point 2 below |CheckAttach-Config|), you need
to enter at least a space, otherwise the plugin won't attach any file to your
mail. If you enter a directory, your filebrowser will be called with that
directory as argument.

The plugin will by default escape blank space in your filename by using '\'.
mutt before version 1.5.20 had a bug, that would not allow you to add files
whose filename contain spaces. If you are using mutt version smaller 1.5.20
this means you would have to rename those files first before attaching them.
(See mutt bug 3179: http://dev.mutt.org/trac/ticket/3179)

Note: Starting with mutt 1.8, there exists the `abort_noattach` quadoption,
which allows to abort sending a message that has no attachments and matches
the `abort_noattach_regexp` option.

Configuration                                        *CheckAttach-Config*
=============

1. Specify different keywords
-----------------------------

You can specify which keywords will be searched by setting the
g:attach_check_keywords variable. By default this variable is specified as:
let g:attach_check_keywords = 'attached,attachment,angehängt,Anhang'
so that it can handle German and English. If you would like to add the keyword
foobar, use this command:

let g:attach_check_keywords =',foobar'

NOTE: The comma is important. It is used to separate the different keywords
and needs to be included.

NOTE: The keywords are matched as regexes, escape an comma with a backslash
if you really need it.

2. Use an external filemanager
------------------------------

Instead of using Vim to select the files, you can also specify to use an
external filemanager. It must be configured to write all selected files into a
temporary file, which in turn will be read in by Vim and put as Attach: header
into your mail. To use an external filebrowser, use the
g:checkattach_filebrowser variable.

Let's assume you want to use ranger (http://ranger.nongnu.org/) as external
file manager. So in your |.vimrc| you put: >

    :let g:checkattach_filebrowser = 'ranger'
<
For ranger, Vim will try to determine, whether it supports the --choosefiles
paramter. This is only supported with Version 1.5.1 of ranger, otherwise, it
will only support the --choosefile parameter. The difference is when using the
--chosefile parameter you can only select 1 file to be attached, while
starting from version 1.5.1 you can attach a list of files. In this case, Vim
will execute the command 'ranger --choosefile/choosefiles=<tempname>' where
<tempname> will be substituted by a temporary file that will be created when
running the command.

You can also force vim to execute a different command, in this case, specify
the command to be run like this: >

    :let g:checkattach_filebrowser = 'ranger --choosefiles=%s'
<
The special parameter '%s' will be replaced by Vim by a temporary filename.
Again, your filebrowser will be expected to write the selected filenames into
that file.

3. Check only once
------------------

You can configure CheckAttach so that it will only check once; on further
writes, it will assume that nothing needs to be done.
To enable this, simply set this variable: >

    :let g:checkattach_once = 'y'
<
4. Check existing headers and escape paths if needed
----------------------------------------------------

CheckAttach by default also checks for each "Attach: " header line, if
the file to be attached needs to have spaces escaped. So it will replace
spaces by "\ " so that mutt is able to find the file and can attach it.
This behaviour is enabled by default. To disable this, simply set this
variable: >

    :let g:checkattach_check_filepath = 0
<
                                                        *CheckAttach_Problems*
Problems with CheckAttach
=========================

If you try to attach a file, whose name contains 8bit letters, it could be,
that mutt can't attach that file and instead displays an error message similar
to this one:

    "<filename>: unable to attach file"

where <filename> is mangled, this is a problem with the way mutt works in
conjunction with the assumed_charset patch. In this case, you should either
not use filenames containing 8bit letters or only 8bit letters in the same
encoding as given to the assumed_charset option.

                                      *EnableCheckAttach* *DisableCheckAttach*
You can disable the plugin by issuing the command >
    :DisableCheckAttach
Enabling the attachment check is then again enabled by issuing >
    :EnableCheckAttach
<
Note: those commands are only available inside a mutt buffer.

If you'd like to suggest adding additional keywords (for your language),
please contact the author (see first line of this help page).

You can also use the ! attribute when saving your buffer to temporarily skip
the check. So if you use :w! the buffer will not be checked for attachments,
only if you use :w it will.

                                                            *:AttachFile*
The plugin also defines the command :AttachFile. This allows you to simply
attach any number of files, using a glob pattern. So, if you like to attach
all your pictures from ~/pictures/ you can simply enter: >

     :AttachFile ~/pictures/*.jpg

and all jpg files will be attached automatically. You can use <Tab> to
complete the directory.

Additionally you can specify different patterns at once:

    :AttachFile ~/pictues/*.jpg ~/Bilder/*.jpg

==============================================================================
2. CheckAttach History                                   *CheckAttach-history*
   (unreleased):
   - Fix a bug, when there was no empty new line in the email and the cursor
     would end up at the last line. This would prevent the plugin to find any
     of the check patterns and therefore not ask for attaching a file.
     (#8, reported by
     tlimbacker, thanks!)
   - Add attach pseudo header after the last real email header
     (#9, reported by
     Konfekt, thanks!)
   - Check for existence of email headers before trying to add Attach
     pseudo header
   - use keywords as regex instead of literal string matches
     (#10, reported by
     Konfekt, thanks!)
   - make use of Neovims :terminal for calling out to ranger
     (PR #14, contributed by has2k1, thanks!)
   - disable attachment checking when `g:attachcheck_once` is set and
     it has already been checked once
     (#17, reported by
     Konfekt, thanks!)
   - Allow to check existing attachment headers and escape file paths
     if needed. (#21, reported by
     Konfekt, thanks!)
   - Do not check the signature
     #25
   0.17: Jan 16, 2015 "{{{1
   - Always use the full path to the attached file. Matters if the working
     directory of mutt and vim disagree.
   - Using :AttachFile with ranger was broken (reported by Ram-Z at
     #5, thanks!)
   0.16: Mar 27, 2014 "{{{1
   - allow to specify several patterns after |:AttachFile| (issue #4,
     #4 reported by AguirreIF,
     thanks!)

   0.15: Aug 13, 2013 "{{{1

   - don't match Attach: header when trying to look for matching attachment
     keywords

   0.14: Jun 16, 2012 "{{{1

   - Fix issue 2 from github: #2
     (:AttachFile, does not correctly attach filenames with spaces, reported by
     daaugusto, thanks!)

   0.13: Nov 08, 2011 "{{{1

    - allow plugin to use an external file manager for selecting the files
      (suggested by mutt-users mailinglist)
    - Command definition will be buffer local
    - Don't check for matches of the keywords in the quoted of the message
      (suggested by Sebastian Tramp, thanks!)
    - Don't check for matches inside the header (start at subject line,
      suggested by Sebastian Tramp, thanks!)
    - Only check as long, as no :Attach header is available when the
      g:checkattach_once variable is set (suggested by Sebastian Tramp,
      thanks!)
    - Documentation update

   0.12: Oct  25, 2011 "{{{1

    - Update the plugin (include some changes, that got lost with 0.11)

   0.11: Sep  30, 2011 "{{{1

    - Make a filetype plugin out of it, it does not make sense to have it as
      plugin, since its only use is with mutt (aka ft: mail)
    - Documentation update

   0.10: Jan  17, 2011 "{{{1

    - Spelling fixes by Scott Stevenson (Thanks!)

    0.9: Dec  17, 2010 "{{{1

    -  new command |:AttachFile|

    0.8: Nov  29, 2010 "{{{1

    - Make ftplugin instead of plugin, don't trigger check of filetypes clear
      matchlist on next run code cleanup

    0.7: May  05, 2010 "{{{1

    - Force checking the filetype

    0.6: May  05, 2010 "{{{1

    - Force filetype detection, which did prevent of the plugin to be working
      correctly
    - Created a public github repository at http://github.com/chrisbra/CheckAttach
    - Small changes to the documentation

    0.5: Mar  02, 2010 "{{{1

    - Search without matching case

    0.4: Jan  26, 2010 "{{{1

    - Highlight matching keywords, use g:attach_check_ft to specify for which
      filetypes to enable the plugin

    0.3: Oct   1, 2009 "{{{1

    - Fixed Copyright statement, enabled GetLatestScripts

    0.2: Sept 29, 2009 "{{{1

    - Added Documentation

    0.1: Sept 29, 2009 "{{{1

    - First working version, using simple commands

==============================================================================
vim:tw=78:ts=8:ft=help:et