X-Git-Url: http://git.marmaro.de/?p=mmh;a=blobdiff_plain;f=docs%2FREADME-ATTACHMENTS;fp=docs%2FREADME-ATTACHMENTS;h=0000000000000000000000000000000000000000;hp=ff9db2a3bacfbc0509353867110a9578e39aab30;hb=731cbed5b971fac4bddd0ea525da0a90be54425b;hpb=9d65b803e9cd65249ea2317c2f43495b9eed40bc diff --git a/docs/README-ATTACHMENTS b/docs/README-ATTACHMENTS deleted file mode 100644 index ff9db2a..0000000 --- a/docs/README-ATTACHMENTS +++ /dev/null @@ -1,281 +0,0 @@ -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