# HG changeset patch # User markus schnalke # Date 1340207857 -7200 # Node ID a782488c85f569331994e26d00b4b3b49b3cbf27 # Parent e8e6adb14bebb0a8923ab57103e43d6a3dd15636 More text about attachments mainly, plus some rearrangements. diff -r e8e6adb14beb -r a782488c85f5 ch01.roff --- a/ch01.roff Wed Jun 20 11:48:52 2012 +0200 +++ b/ch01.roff Wed Jun 20 17:57:37 2012 +0200 @@ -112,6 +112,39 @@ As the MH tool chest was modeled after the Unix tool chest, the properties of the latter apply to the former as well. + +.ig \"XXX + +.P +To ease typing, the switches can be abbreviated as much as the remaining +prefix remains unambiguous. +If in our example no other switch would start with the letter `t', then +.Cl "-truncate" , +.Cl "-trunc" , +.Cl "-tr" , +and +.Cl "-t +would all be the same. +As a result, switches can neither be grouped (as in +.Cl "ls -ltr" ) +nor can switch arguments be appended directly to the switch (as in +.Cl "sendmail -q30m" ). +.P +Many switches have negating counter-parts, which start with `no'. +For example +.Cl "-notruncate +inverts the +.Cl "-truncate +switch. +They exist to undo the effect of default switches in the profile. +If the user has chosen to change the default behavior of some tool +by adding a default switch to the profile, +he can still undo this change in behavior by specifying the inverse +switch on the command line. + +.. + + .U2 "Using MH .P It is strongly recommended to have a look at the MH Book, diff -r e8e6adb14beb -r a782488c85f5 ch03.roff --- a/ch03.roff Wed Jun 20 11:48:52 2012 +0200 +++ b/ch03.roff Wed Jun 20 17:57:37 2012 +0200 @@ -1096,7 +1096,7 @@ switch, are sufficient. -.U3 "Inplace Editing +.U3 "In Place Editing .P .Pn anno had the switches @@ -1608,32 +1608,6 @@ .ig .P -To ease typing, the switches can be abbreviated as much as the remaining -prefix remains unambiguous. -If in our example no other switch would start with the letter `t', then -.Cl "-truncate" , -.Cl "-trunc" , -.Cl "-tr" , -and -.Cl "-t -would all be the same. -As a result, switches can neither be grouped (as in -.Cl "ls -ltr" ) -nor can switch arguments be appended directly to the switch (as in -.Cl "sendmail -q30m" ). -.P -Many switches have negating counter-parts, which start with `no'. -For example -.Cl "-notruncate -inverts the -.Cl "-truncate -switch. -They exist to undo the effect of default switches in the profile. -If the user has chosen to change the default behavior of some tool -by adding a default switch to the profile, -he can still undo this change in behavior by specifying the inverse -switch on the command line. -.P In the best case, all switches are unambiguous on the first character, or on the three-letter prefix for the `no' variants. Reducing switch prefix collisions, shortens the necessary prefix length @@ -1643,59 +1617,49 @@ .. +.\" XXX: whatnow prompt commands + + .H1 "Modernizing +.P +The code base of mmh originates from the late Seventies. +Through the Eighties, extensive work had been done on it. +In the Nineties, it had been partly reorganized and extended. +Relicts from each decade have gathered in the code base. +My goal was to modernize the code base. + +.P +FIXME functional aspect only here +.P +FIXME ref to `code style' for non-functional aspects. .H2 "Code Relicts .P -The code base of mmh originates from the late Seventies, -had been extensively -worked on in the mid Eighties, and had been partly reorganized and extended -in the Nineties. Relicts of all those times had gathered in the code base. -My goal was to remove any ancient code parts. One part of the task was -converting obsolete code constructs to standard constructs, the other part -was dropping obsolete functions. -.P -As I'm not even thirty years old and have no more than seven years of -Unix experience, I needed to learn about the history in retrospective. -Older people likely have used those ancient constructs themselves -and have suffered from their incompatibilities and have longed for -standardization. Unfortunately, I have only read that others had done so. -This put me in a much more difficult positions when working on the old -code. I needed to recherche what other would have known by heart from -experience. All my programming experience comes from a time past ANSI C -and past POSIX. Although I knew about the times before, I took the -current state implicitly for granted most of the time. -.P -Being aware of -these facts, I rather let people with more historic experience solve the -task of converting the ancient code constructs to standardized ones. -Luckily, Lyndon Nerenberg focused on this task at the nmh project. -He converted large parts of the code to POSIX constructs, removing -the conditionals compilation for now standardized features. -I'm thankful for this task being solved. I only pulled the changes into -mmh. -.P -The other task \(en dropping ancient functionality to remove old code \(en -I did myself, though. My position to strip mmh to the bare minimum of -frequently used features is much more revolutional than the nmh community -likes it. Without the need to justify my decisions, I was able to quickly +My position to drop obsolete functionality of mmh to remove old code +is much more revolutional than the nmh community likes it. +Without the need to justify my decisions, I was able to quickly remove functionality I considered ancient. The need to discuss my decisions with -peers likely would have slowed this process down. Of course, I researched -if a particular feature really should be dropped. Having not had any +peers likely would have slowed this process down. +Of course, I researched if a particular feature really should be dropped. +Having not had any contact to this feature within my computer life was a first indicator to drop it, but I also asked others and searched the literature for modern -usage of the feature. If it appeared to be truly ancient, I dropped it. +usage of the feature. +If it appeared to be truly ancient, I dropped it. The reason for dropping is always part of the commit message in the -version control system. Thus, it is easy for others to check their +version control system. +Thus, it is easy for others to check their view on the topic with mine and possibly to argue for reinclusion. + .U3 "MMDF maildrop support .P -I did drop any support for the MMDF maildrop format. This type of format +I did drop any support for the MMDF maildrop format. +This type of format is conceptionally similar to the mbox format, but uses four bytes with value 1 (\fL^A^A^A^A\fP) as message delimiter, instead of the string ``\fLFrom\ \fP''. @@ -1703,11 +1667,11 @@ format on Unix, but also due to the larger influence of Sendmail than MMDF, the MMDF maildrop format had vanished. .P -The simplifications within the code were only moderate. Switches could -be removed from tools like +The simplifications within the code were only moderate. +Switches could be removed from tools like .L packf , -which generate packed mailboxes. Only one packed mailbox format remained: -mbox. +which generate packed mailboxes. +Only one packed mailbox format remained: mbox. The most important changes affect the equally named mail parsing routine in .L sbr/m_getfld.c . The direct MMDF code had been removed, but as now only one packed mailbox @@ -1717,18 +1681,21 @@ .Fu m_getfld() . Changes beyond a small local scope \(en which restructuring in its core is \(en cause a high risk of damaging -the intricate workings of the optimized code. This problem is know -to the developers of nmh, too. They also avoid touching this minefield -if possible. +the intricate workings of the optimized code. +This problem is know to the developers of nmh, too. +They also avoid touching this minefield if possible. .U3 "UUCP Bang Paths .P More questionably than the former topic is the removal of support for the -UUCP bang path address style. However, the user may translate the bang +UUCP bang path address style. +However, the user may translate the bang paths on retrieval to Internet addresses and the other way on posting -messages. The former can be done my an MDA like procmail; the latter -by a sendmail wrapper. This would ensure that any address handling would -work as expected. However, it might just work well without any +messages. +The former can be done my an MDA like procmail; the latter +by a sendmail wrapper. +This would ensure that any address handling would work as expected. +However, it might just work well without any such modifications, as mmh does not touch addresses much, in general. But I can't ensure as I have never used an environment with bang paths. Also, the behavior might break at any point in further development. @@ -1743,8 +1710,8 @@ The check only prevented a pager to be placed between the outputting program (\c .Pn mhl ) -and the terminal. This could have been ensured with -the +and the terminal. +This could have been ensured with the .Sw -nomoreproc at the command line statically, too. @@ -1753,7 +1720,8 @@ The .Hd Encrypted header field had been introduced by RFC\^822, but already -marked legacy in RFC 2822. It was superseded by FIXME. +marked legacy in RFC 2822. +It was superseded by FIXME. Mmh does no more support this header field. .P Native support for @@ -1907,10 +1875,15 @@ Thus, MH had all the MIME features but no idea of attachments. Today, however, users don't need all the MIME features but they want convenient attachment handling. -In order to solve this problem, in 2002, Jon Steinhart had added an -attachment system to nmh. + +.U3 "Composing MIME Messages +.P +In order to improve the situation on the message composing side, +Jon Steinhart had added an attachment system to nmh in 2002. .Ci 7480dbc14bc90f2d872d434205c0784704213252 -He described his motivation to do so as such: +In the file +.Fn docs/README-ATTACHMENTS , +he described his motivation to do so as such: .QS Although nmh contains the necessary functionality for MIME message handing, the interface to this functionality is pretty obtuse. @@ -1918,41 +1891,36 @@ .Pn mhbuild composition files! .QE -With this change, the mind model of attachments entered nmh: +.LP +With this change, the mind model of attachments entered nmh. +In the same document: .QS 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. .QE -Unfortunately, the system had been deactivated by default, -like any new facilities in nmh. -.\" XXX move this paragraph somewhere else -Just to give one example, for me it took one year of using nmh -before I became aware of the existence of the attachment system. -One could argue that this fact disqualifies my reading of the -documentation. -If I would have installed nmh from source back then, I could agree. -Yet I had used a prepackaged version and had expected that it would -just work. +.LP +Unfortunately, the attachment system, +like any new facilities in nmh, +was deactive by default. .P During my work in Argentina, I tried to improve the attachment system. -Because of great opposition in the nmh community, after long discussions, -my patch died as a proposal on the mailing list. +But, because of great opposition in the nmh community, +my patch died as a proposal on the mailing list, after long discussions. .[ nmh-workers attachment proposal .] -In Januar 2012, I applied the patch in an extended form to mmh. +In Januar 2012, I extended the patch and applied it to mmh. .Ci 8ff284ff9167eff8f5349481529332d59ed913b1 +In mmh, the attachment system is active by default. +Instead of command line switches, the +.Pe Attachment-Header +profile entry is used to specify +the name of the attachment header field. +It is pre-defined to +.Hd Attach . .P -In mmh, the attachment system is active by default. -There are no command line switches anymore, but a pre-defined attachment -header field. -It is named -.Hd Attach -by default, but can be renamed with the -.Pe Attachment-Header -profile entry. To add an attachment to a draft, simply add an attachment header: .VS To: bob @@ -1962,20 +1930,21 @@ Here it is. VE The header field can be added to the draft manually in the editor, -by using the `attach' command at the WhatNow prompt, or with +or by using the `attach' command at the WhatNow prompt, or +non-interactively with .Pn anno : .VS -anno -append -nodate -component Attach -text /path/to/file +anno -append -nodate -component Attach -text /path/to/attachment VE -Drafts with attachment headers are converted to MIME automatically -on sending. -The draft stored in the draft folder is always in source form with +Drafts with attachment headers are converted to MIME automatically by +.Pn send . +The conversion to MIME is invisible to the user. +The draft stored in the draft folder is always in source form, with attachment headers. -The convertion to MIME is done invisible to the user. If the MIMEification fails, for instance because the file to attach is not accessible, the original draft is not changed. .P -Forwarding message is handled by the same attachment system. +The attachment system handles the forwarding of messages, too. If the attachment header value starts with a plus character (`+'), like in .Cl "Attach: +bob 30 42" , @@ -1986,58 +1955,128 @@ .P Closely related to attachments is non-ASCII text content, because it requires MIME too. -In nmh it the user needed to invoke `mime' at the WhatNow prompt +In nmh, the user needed to call `mime' at the WhatNow prompt to have the draft converted to MIME. -This was necessary if the draft contained non-ASCII characters. +This was necessary whenever the draft contained non-ASCII characters. If the user did not call `mime', a broken message would be sent. Therefore, the .Pe automimeproc profile entry could be specified to have the `mime' command invoked -automatically for each message. +automatically each time. Unfortunately, this approach conflicted with with attachment system because the draft would already be in MIME format at the time when the attachment system wanted to MIMEify it. -To use the attachment system, the user must not run `mime' at the -WhatNow prompt nor have +To use nmh's attachment system, `mime' must not be called at the +WhatNow prompt and .Pe automimeproc -set in the profile. +must not be set in the profile. But then the case of non-ASCII text without attachment headers was not caught. -All in all a bad solution. -My patch from December 2010 already solved this situation. +All in all, the solution was complex and irritating. +My patch from December 2010 would have simplified the situation. +.P Mmh's current solution is even more elaborate. Any necessary MIMEification is done automatically. There is no `mime' command at the WhatNow prompt anymore. -The draft will be converted to MIME when either an attachment header -or non-ASCII text is present. +The draft will be converted automatically to MIME when either an +attachment header or non-ASCII text is present. Further more, the special meaning of the hash character (`#') -at the beginning of the line in the draft message is removed. -The user needs not at all deal about the topic. +at line beginnings in the draft message is removed. +Users need not at all deal with the whole topic. .P -This improvement has a price: The new approach does not directly -support arbitrary MIME compositions. -Nonetheless, the full power of +Although the new approach does not anymore support arbitrary MIME +compositions directly, the full power of .Pn mhbuild can still be accessed. -As long as no attachment headers are included, the user can create a -nonlimited +Given no attachment headers are included, the user can create .Pn mhbuild -composition draft like in nmh. +composition drafts like in nmh. Then, at the WhatNow prompt, he needs to invoke .Cl "edit mhbuild to convert it to MIME. -Because the resulting draft does only contain ASCII characters -and has no attachment headers, the attachment system will not touch it. +Because the resulting draft does neither contain non-aASCII characters +nor has it attachment headers, the attachment system will not touch it. .P The approach taken in mmh is taylored towards todays most common case: a text part with possibly attachments. -Still, the full power of +This case is simplified a lot for users. + +.U3 "MIME Type Guessing +.P +The use of .Pn mhbuild -can be accessed with a bit of overhead. +composition drafts had one notable advantage over attachment headers +from the programmer's point of view: The user provides the appropriate +MIME types for files to include. +The attachment system needs to find out the correct MIME type itself. +This is a difficult task, yet it spares the user irritating work. +Determining the correct MIME type of content is partly mechanical, +partly intelligent work. +Forcing the user to find out the correct MIME type, +forces him to do partly mechanical work. +Letting the computer do the work, can lead to bad choices for difficult +content. +For mmh, the latter option was chosen. +.P +Determining the MIME type by the suffix of the file name is a dumb +approach, yet it is simple to implement and provides good results +for the common cases. +Mmh implements this approach in the +.Pn print-mimetype +script. +Using it is the default choice. +.P +A far better but less portable approach is the use of +.Pn file . +This standard tool tries to determine the type of files. +Unfortunately, its capabilities and accuracy varies from system to system. +Additionally, its output was only intended for human beings, +but not to be used by programs. +It varies much. +Nevertheless, modern versions of GNU +.Pn file , +which is prevalent on the popular GNU/Linux systems, +provides MIME type output in machine-readable form. +Although this solution is highly system-dependent, +it solves the difficult problem well. +On systems where GNU +.Pn file , +version 5.04 or higher, is available it should be used. +One needs to specify the following profile entry to do so: +.VS +Mime-Type-Query: file -b --mime +VE +.LP +Other versions of +.Pn file +might possibly be usable with wrapper scripts to reformat the output. +The diversity among +.Pn file +implementations is great; one needs to check the local variant. +.P +If no MIME type can be determined, text content gets sent as +`text/plain' and anything else under the generic fall-back type +`application/octet-stream'. +It is not possible in mmh to override the automatic MIME type guessing +for a specific file. +To do so, the user would need to know in advance for which file +the automatic guessing does fail, or the system would require interaction. +I consider both cases impractical. +The existing solution should be sufficient. +If not, the user may always fall back to +.Pn mhbuild +composition drafts and ignore the attachment system. -.\" XXX: MIME types -.\" XXX: whatnow prompt commands -.\" XXX: anno rework + +.U3 "Storing Attachments +.P +FIXME + + +.U3 "Showing MIME Messages +.P +FIXME + .H2 "Digital Cryptography @@ -2045,10 +2084,16 @@ Signing and encryption. -.H2 "Good Defaults + +.H2 "Modern Defaults .P -foo - +Just to give one example, for me it took one year of using nmh +before I became aware of the existence of the attachment system. +One could argue that this fact disqualifies my reading of the +documentation. +If I would have installed nmh from source back then, I could agree. +Yet I had used a prepackaged version and had expected that it would +just work. @@ -2061,6 +2106,36 @@ .P POSIX +.U3 "Converting to Standard Code +.P +One part of this task was converting obsolete code constructs +to standard constructs. +As I'm not even thirty years old and have no more than seven years of +Unix experience, I needed to learn about the history in retrospective. +Older people likely have used those ancient constructs themselves +and have suffered from their incompatibilities and have longed for +standardization. +Unfortunately, I have only read that others had done so. +This put me in a much more difficult positions when working on the old +code. +I needed to recherche what other would have known by heart from +experience. +All my programming experience comes from a time past ANSI C +and past POSIX. +Although I knew about the times before, I took the +current state implicitly for granted most of the time. +.P +Being aware of +these facts, I rather let people with more historic experience solve the +task of converting the ancient code constructs to standardized ones. +Luckily, Lyndon Nerenberg focused on this task at the nmh project. +He converted large parts of the code to POSIX constructs, removing +the conditionals compilation for now standardized features. +I'm thankful for this task being solved. I only pulled the changes into +mmh. + + + .H2 "Separation @@ -2171,6 +2246,9 @@ .P Code layout, goto, ... +.P +anno rework +