--- /dev/null
+Jon Steinhart's (jon@fourwinds.com) Attachment Handling Mods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A bunch of changes have been made to improve the nmh user interface for
+handling MIME attachments.
+
+Why Did I Do This?
+~~~~~~~~~~~~~~~~~~
+
+Although nmh contains the necessary functionality for MIME message handing,
+the interface to this functionality is pretty obtuse. There's no way that
+I'm ever going to convince my partner to write mhbuild composition files!
+And even though I know how to write them, I often screw up when sending a
+message that contains a shell script because I forget that I have to double
+any # at the start of a line, which shell scripts have galore.
+
+These changes simplify the task of managing attachments on draft files.
+They allow attachments to be added, listed, and deleted. MIME messages are
+automatically created when drafts with attachments are sent.
+
+The Simple Setup
+~~~~~~~~~~~~~~~~
+
+The gory details are all given below. Here's how to set things up simply. This
+only works if you're using the "standard" interface, i.e., whatnow. Life is more
+complicated if you run mh-e.
+
+Add the following to your .mh_profile:
+
+ send: -attach X-MH-Attachment
+ whatnow: -attach X-MH-Attachment
+
+You may already have send and whatnow lines in your .mh_profile; if you do, just add
+the new stuff to the end of the line. For example, mine looks like:
+
+ send: -alias aliases -attach X-MH-Attachment
+ whatnow: -attach X-MH-Attachment
+
+That's it. Next time you want to send an attachment, say "attach filename" at the
+whatnow prompt and you're done. You can check your attachments by saying "alist".
+
+Did I Do This Correctly?
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Hard to say. Despite lots of time looking at the nmh code, I can't say that
+I get the philosophy behind its structure.
+
+I am aware of two deviations from what I saw in the nmh code.
+
+ 1. I commented my changes.
+
+ 2. It's been years since I've used a VT-100, so I don't try to make code
+ fit into 80 columns anymore. Seems silly to me.
+
+What Did I Do?
+~~~~~~~~~~~~~~
+
+I made changes to the following files:
+
+ h/
+ prototypes.h
+ man/
+ anno.man
+ send.man
+ whatnow.man
+ uip/
+ Makefile.in
+ anno.c
+ annosbr.c
+ send.c
+ sendsbr.c
+ viamail.c (needed change for new sendsbr argument)
+ whatnowsbr.c
+
+Attachments are associated with messages using header fields. For example, a
+draft that looks like this
+
+ To: jon
+ Subject: test of attachments
+ X-MH-Attachment: /export/home/jon/foo
+ X-MH-Attachment: /export/home/jon/bar
+ X-MH-Attachment: /export/home/jon/test/foo
+ --------
+
+has the files "foo", "bar", and foo as attachments.
+
+Although I use the header field name "X-MH-Attachment" to indicate
+attachments, the implementation allows any header field name.
+
+The advantage of using header fields is that the list of attachments
+travels with the draft so it remains valid across editing sessions.
+
+Note that the header fields for attachments are removed from the message
+before it is sent.
+
+Since I was adding header fields to messages, it seemed sensible to use the
+existing anno program to do this for me. This required several changes to
+generalize anno:
+
+ o I added a -draft option that permits annotations (header fields) to
+ be added to the draft instead of a message sequence.
+
+ o I added a -delete option that allows annotations to be deleted.
+
+ o I added a -list option that allows annotations to be listed.
+
+ o I added a -number option that modifies the behavior of -delete and -list.
+
+ o I added a -append option so that annotations are appended to the headers
+ instead of the default prepend. Without this, attachments come out in
+ reverse order.
+
+Using the modified anno, the example above could be created (assuming that the
+draft exists) by
+
+ prompt% anno -draft -comp X-MH-Attachment -text /export/home/jon/foo -nodate -append
+ prompt% anno -draft -comp X-MH-Attachment -text /export/home/jon/bar -nodate -append
+ prompt% anno -draft -comp X-MH-Attachment -text /export/home/jon/test/foo -nodate -append
+
+One can quite easily make an "attach" command using shell scripts, aliases or functions.
+For example, here's a bash function that does the job:
+
+ function attach() { for i in $*; do anno -append -nodate -draft -comp X-MH-Attachment -text "$i"; done; }
+
+The following examples show the different ways in which attachments can be
+listed.
+
+ prompt% anno -list -draft -comp X-MH-Attachment
+ foo
+ bar
+ foo
+
+ prompt% anno -list -draft -comp X-MH-Attachment -text /
+ /export/home/jon/foo
+ /export/home/jon/bar
+ /export/home/jon/test/foo
+
+ prompt% anno -list -draft -comp X-MH-Attachment -number
+ 1 foo
+ 2 bar
+ 3 foo
+
+ prompt% anno -list -draft -comp X-MH-Attachment -text / -number
+ 1 /export/home/jon/foo
+ 2 /export/home/jon/bar
+ 3 /export/home/jon/test/foo
+
+ prompt%
+
+Why all these listing options?
+
+I feel that the listing as produced by the first example is what most people
+would want most of the time.
+
+The listing as produced by the second example seemed necessary for situations
+where there were several attachments with the same file name in different
+directories.
+
+I included the numbering option so that attachments could be deleted by number
+which might be easier in situations where there were several attachments with
+the same file name in different directories, as in the above example.
+
+Attachments are deleted using the -delete option.
+
+ prompt% anno -delete -draft -comp X-MH-Attachment -text foo
+
+deletes the first attachment since the foo matches the basename of the attachment
+name.
+
+ prompt% anno -delete -draft -comp X-MH-Attachment -text /export/home/jon/test/foo
+
+deletes the third attachment since the text is a full path name and matches.
+
+ prompt% anno -delete -draft -comp X-MH-Attachment -number 2
+
+deletes the second attachment.
+
+The attachment annotations are converted to a MIME message by send. I'm not
+completely sure that this is the right place to do it, as opposed to doing
+it in post, but both would work. It seemed to me to make more sense to do
+it in send so that all of the various post options would apply to the MIME
+message instead of the original draft file.
+
+I added an -attach option to send that specifies the header field name used
+for attachments. Send performs the following additional steps if this option
+is set:
+
+ o It scans the header of the draft for attachments. Normal behavior applies
+ if none exist.
+
+ o A temporary mhbuild composition file is created if there are attachments.
+
+ o All non-attachment headers are copied from the draft file to the
+ composition file.
+
+ o The body of the draft is copied to a temporary body file if it contains at
+ least one non-whitespace character. A mhbuild directive for this file is
+ appended to the composition file. Note that this eliminates the problem
+ of lines beginning with the # character in the message body.
+
+ o A mhbuild directive is appended to the composition file for each attachment
+ header.
+
+ o mhbuild is run on the composition file, converting it to a MIME message.
+
+ o The converted composition file is substituted for the original draft file
+ and run through the rest of send.
+
+ o The original draft file is renamed instead of the converted composition
+ file. This preserves the original message instead of the composition file
+ which is really what a user would want.
+
+ o The ,file.orig file created by mhbuild is removed as it's a nuisance.
+
+The mhbuild directives appended to the composition file are constructed as
+follows:
+
+ o The content-type a file with a dot-suffix is obtained from the list of
+ mhshow-suffix- entries in the profile.
+
+ o A file with no dot-suffix or no entry in the profile is assigned a
+ content-type of application/octet-stream if it contains any non-ASCII
+ characters.
+
+ o A file with no dot-suffix or no entry in the profile is assigned a
+ content-type of text/plain if it contains only ASCII characters.
+
+ o The directive is of the form:
+
+ #content-type; name="basename"; x-unix-mode=mode [ description ] filename
+
+ The content type is derived as discussed above. The basename is the
+ last component of the pathname given in the body of the attachment header
+ field. The mode is file permissions. The description is obtained by
+ running the file command on the attachment file. The filename is the
+ field body from the attachment header field.
+
+I added an -attach option to whatnow that specifies the header field name for
+attachments.
+
+I added to the commands available at the whatnow prompt to provide an interface
+to the attachment mechanism.
+
+I'm not completely happy with some of these additions because they duplicate
+shell functionality. I'm not sure that there's a good way around it other than
+to not use whatnow.
+
+The first three additions (the ones I'm not happy with) are cd, ls, and pwd.
+These do the same thing as their system counterparts. As a matter of fact,
+these are implemented by running the commands in a subshell. I did this because
+I wanted proper interpretation of shell-specific things like ~ and wildcard
+expansion.
+
+The next command is attach. This takes a list of files and adds them to the draft
+as attachments using the same code as the modified anno. The list of files is
+run through ls using the user's shell, so wildcard expansion and all that works.
+
+The alist command lists the attachments on the current draft using listing function
+that I added to anno. It takes two optional options, -l for a long listing meaning
+full path names, and -n for a numbered listing.
+
+The detach command removes attachments from the current draft, again using the
+modified anno. The arguments are interpreted as numbers if the -n option is used,
+otherwise they're interpreted as file names. File names are shoveled through ls
+using the user's shell in the directory containing the file for wildcard expansion
+and such. File names are matched against the last pathname component unless they
+begin with a / in which case they're matched against the entire name.
+
+What's Left To Do?
+~~~~~~~~~~~~~~~~~~
+
+Nothing on this stuff. When I get time I'd like to improve the interface
+for reading messages with attachments. It's my opinion that, because of the
+command line nature of nmh, it makes the most sense to treat attachments as
+separate messages. In other words one should be able to read the next
+attachment using next, and the previous one using prev. One should be able
+to show and scan attachments. This would probably involve a major change
+in the message numbering scheme to allow something like 123.4 to indicate
+attachment 4 on message 123.
+
+ Jon Steinhart
projects / mmh / commitdiff