From: Jon Steinhart Date: Thu, 22 Aug 2002 22:06:18 +0000 (+0000) Subject: Moved this file here from the root directory. X-Git-Tag: RELEASE_1_2~116 X-Git-Url: http://git.marmaro.de/?a=commitdiff_plain;h=982194e9f1c9e4718b4857b300fc3ab8b16c8f6b;p=mmh Moved this file here from the root directory. --- diff --git a/docs/README-ATTACHMENTS b/docs/README-ATTACHMENTS new file mode 100644 index 0000000..ff9db2a --- /dev/null +++ b/docs/README-ATTACHMENTS @@ -0,0 +1,281 @@ +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