1.1 --- a/ch03.roff	Wed Jun 20 11:48:52 2012 +0200
     1.2 +++ b/ch03.roff	Wed Jun 20 17:57:37 2012 +0200
     1.3 @@ -1096,7 +1096,7 @@
     1.4  switch, are sufficient.
     1.5  
     1.6  
     1.7 -.U3 "Inplace Editing
     1.8 +.U3 "In Place Editing
     1.9  .P
    1.10  .Pn anno
    1.11  had the switches
    1.12 @@ -1608,32 +1608,6 @@
    1.13  .ig
    1.14  
    1.15  .P
    1.16 -To ease typing, the switches can be abbreviated as much as the remaining
    1.17 -prefix remains unambiguous.
    1.18 -If in our example no other switch would start with the letter `t', then
    1.19 -.Cl "-truncate" ,
    1.20 -.Cl "-trunc" ,
    1.21 -.Cl "-tr" ,
    1.22 -and
    1.23 -.Cl "-t
    1.24 -would all be the same.
    1.25 -As a result, switches can neither be grouped (as in
    1.26 -.Cl "ls -ltr" )
    1.27 -nor can switch arguments be appended directly to the switch (as in
    1.28 -.Cl "sendmail -q30m" ).
    1.29 -.P
    1.30 -Many switches have negating counter-parts, which start with `no'.
    1.31 -For example
    1.32 -.Cl "-notruncate
    1.33 -inverts the
    1.34 -.Cl "-truncate
    1.35 -switch.
    1.36 -They exist to undo the effect of default switches in the profile.
    1.37 -If the user has chosen to change the default behavior of some tool
    1.38 -by adding a default switch to the profile,
    1.39 -he can still undo this change in behavior by specifying the inverse
    1.40 -switch on the command line.
    1.41 -.P
    1.42  In the best case, all switches are unambiguous on the first character,
    1.43  or on the three-letter prefix for the `no' variants.
    1.44  Reducing switch prefix collisions, shortens the necessary prefix length
    1.45 @@ -1643,59 +1617,49 @@
    1.46  ..
    1.47  
    1.48  
    1.49 +.\" XXX: whatnow prompt commands
    1.50 +
    1.51 +
    1.52  
    1.53  
    1.54  .H1 "Modernizing
    1.55 +.P
    1.56 +The code base of mmh originates from the late Seventies.
    1.57 +Through the Eighties, extensive work had been done on it.
    1.58 +In the Nineties, it had been partly reorganized and extended.
    1.59 +Relicts from each decade have gathered in the code base.
    1.60 +My goal was to modernize the code base.
    1.61 +
    1.62 +.P
    1.63 +FIXME functional aspect only here
    1.64 +.P
    1.65 +FIXME ref to `code style' for non-functional aspects.
    1.66  
    1.67  
    1.68  .H2 "Code Relicts
    1.69  .P
    1.70 -The code base of mmh originates from the late Seventies,
    1.71 -had been extensively
    1.72 -worked on in the mid Eighties, and had been partly reorganized and extended
    1.73 -in the Nineties. Relicts of all those times had gathered in the code base.
    1.74 -My goal was to remove any ancient code parts. One part of the task was
    1.75 -converting obsolete code constructs to standard constructs, the other part
    1.76 -was dropping obsolete functions.
    1.77 -.P
    1.78 -As I'm not even thirty years old and have no more than seven years of
    1.79 -Unix experience, I needed to learn about the history in retrospective.
    1.80 -Older people likely have used those ancient constructs themselves
    1.81 -and have suffered from their incompatibilities and have longed for
    1.82 -standardization. Unfortunately, I have only read that others had done so.
    1.83 -This put me in a much more difficult positions when working on the old
    1.84 -code. I needed to recherche what other would have known by heart from
    1.85 -experience. All my programming experience comes from a time past ANSI C
    1.86 -and past POSIX. Although I knew about the times before, I took the
    1.87 -current state implicitly for granted most of the time.
    1.88 -.P
    1.89 -Being aware of
    1.90 -these facts, I rather let people with more historic experience solve the 
    1.91 -task of converting the ancient code constructs to standardized ones.
    1.92 -Luckily, Lyndon Nerenberg focused on this task at the nmh project.
    1.93 -He converted large parts of the code to POSIX constructs, removing
    1.94 -the conditionals compilation for now standardized features.
    1.95 -I'm thankful for this task being solved. I only pulled the changes into
    1.96 -mmh.
    1.97 -.P
    1.98 -The other task \(en dropping ancient functionality to remove old code \(en
    1.99 -I did myself, though. My position to strip mmh to the bare minimum of
   1.100 -frequently used features is much more revolutional than the nmh community
   1.101 -likes it. Without the need to justify my decisions, I was able to quickly
   1.102 +My position to drop obsolete functionality of mmh to remove old code
   1.103 +is much more revolutional than the nmh community likes it.
   1.104 +Without the need to justify my decisions, I was able to quickly
   1.105  remove functionality I considered ancient.
   1.106  The need to discuss my decisions with
   1.107 -peers likely would have slowed this process down. Of course, I researched
   1.108 -if a particular feature really should be dropped. Having not had any
   1.109 +peers likely would have slowed this process down.
   1.110 +Of course, I researched if a particular feature really should be dropped.
   1.111 +Having not had any
   1.112  contact to this feature within my computer life was a first indicator to
   1.113  drop it, but I also asked others and searched the literature for modern
   1.114 -usage of the feature. If it appeared to be truly ancient, I dropped it.
   1.115 +usage of the feature.
   1.116 +If it appeared to be truly ancient, I dropped it.
   1.117  The reason for dropping is always part of the commit message in the
   1.118 -version control system. Thus, it is easy for others to check their
   1.119 +version control system.
   1.120 +Thus, it is easy for others to check their
   1.121  view on the topic with mine and possibly to argue for reinclusion.
   1.122  
   1.123 +
   1.124  .U3 "MMDF maildrop support
   1.125  .P
   1.126 -I did drop any support for the MMDF maildrop format. This type of format
   1.127 +I did drop any support for the MMDF maildrop format.
   1.128 +This type of format
   1.129  is conceptionally similar to the mbox format, but uses four bytes with
   1.130  value 1 (\fL^A^A^A^A\fP) as message delimiter,
   1.131  instead of the string ``\fLFrom\ \fP''.
   1.132 @@ -1703,11 +1667,11 @@
   1.133  format on Unix, but also due to the larger influence of Sendmail than MMDF,
   1.134  the MMDF maildrop format had vanished.
   1.135  .P
   1.136 -The simplifications within the code were only moderate. Switches could
   1.137 -be removed from tools like
   1.138 +The simplifications within the code were only moderate.
   1.139 +Switches could be removed from tools like
   1.140  .L packf ,
   1.141 -which generate packed mailboxes. Only one packed mailbox format remained:
   1.142 -mbox.
   1.143 +which generate packed mailboxes.
   1.144 +Only one packed mailbox format remained: mbox.
   1.145  The most important changes affect the equally named mail parsing routine in
   1.146  .L sbr/m_getfld.c .
   1.147  The direct MMDF code had been removed, but as now only one packed mailbox
   1.148 @@ -1717,18 +1681,21 @@
   1.149  .Fu m_getfld() .
   1.150  Changes beyond a small local scope \(en
   1.151  which restructuring in its core is \(en cause a high risk of damaging
   1.152 -the intricate workings of the optimized code. This problem is know
   1.153 -to the developers of nmh, too. They also avoid touching this minefield
   1.154 -if possible.
   1.155 +the intricate workings of the optimized code.
   1.156 +This problem is know to the developers of nmh, too.
   1.157 +They also avoid touching this minefield if possible.
   1.158  
   1.159  .U3 "UUCP Bang Paths
   1.160  .P
   1.161  More questionably than the former topic is the removal of support for the
   1.162 -UUCP bang path address style. However, the user may translate the bang
   1.163 +UUCP bang path address style.
   1.164 +However, the user may translate the bang
   1.165  paths on retrieval to Internet addresses and the other way on posting
   1.166 -messages. The former can be done my an MDA like procmail; the latter
   1.167 -by a sendmail wrapper. This would ensure that any address handling would
   1.168 -work as expected. However, it might just work well without any
   1.169 +messages.
   1.170 +The former can be done my an MDA like procmail; the latter
   1.171 +by a sendmail wrapper.
   1.172 +This would ensure that any address handling would work as expected.
   1.173 +However, it might just work well without any
   1.174  such modifications, as mmh does not touch addresses much, in general.
   1.175  But I can't ensure as I have never used an environment with bang paths.
   1.176  Also, the behavior might break at any point in further development.
   1.177 @@ -1743,8 +1710,8 @@
   1.178  The check only prevented a pager to be placed between the outputting
   1.179  program (\c
   1.180  .Pn mhl )
   1.181 -and the terminal. This could have been ensured with
   1.182 -the
   1.183 +and the terminal.
   1.184 +This could have been ensured with the
   1.185  .Sw -nomoreproc
   1.186  at the command line statically, too.
   1.187  
   1.188 @@ -1753,7 +1720,8 @@
   1.189  The
   1.190  .Hd Encrypted
   1.191  header field had been introduced by RFC\^822, but already
   1.192 -marked legacy in RFC 2822. It was superseded by FIXME.
   1.193 +marked legacy in RFC 2822.
   1.194 +It was superseded by FIXME.
   1.195  Mmh does no more support this header field.
   1.196  .P
   1.197  Native support for
   1.198 @@ -1907,10 +1875,15 @@
   1.199  Thus, MH had all the MIME features but no idea of attachments.
   1.200  Today, however, users don't need all the MIME features but they want
   1.201  convenient attachment handling.
   1.202 -In order to solve this problem, in 2002, Jon Steinhart had added an
   1.203 -attachment system to nmh.
   1.204 +
   1.205 +.U3 "Composing MIME Messages
   1.206 +.P
   1.207 +In order to improve the situation on the message composing side,
   1.208 +Jon Steinhart had added an attachment system to nmh in 2002.
   1.209  .Ci 7480dbc14bc90f2d872d434205c0784704213252
   1.210 -He described his motivation to do so as such:
   1.211 +In the file
   1.212 +.Fn docs/README-ATTACHMENTS ,
   1.213 +he described his motivation to do so as such:
   1.214  .QS
   1.215  Although nmh contains the necessary functionality for MIME message handing,
   1.216  the interface to this functionality is pretty obtuse.
   1.217 @@ -1918,41 +1891,36 @@
   1.218  .Pn mhbuild
   1.219  composition files!
   1.220  .QE
   1.221 -With this change, the mind model of attachments entered nmh:
   1.222 +.LP
   1.223 +With this change, the mind model of attachments entered nmh.
   1.224 +In the same document:
   1.225  .QS
   1.226  These changes simplify the task of managing attachments on draft files.
   1.227  They allow attachments to be added, listed, and deleted.
   1.228  MIME messages are automatically created when drafts with attachments
   1.229  are sent.
   1.230  .QE
   1.231 -Unfortunately, the system had been deactivated by default,
   1.232 -like any new facilities in nmh.
   1.233 -.\" XXX move this paragraph somewhere else
   1.234 -Just to give one example, for me it took one year of using nmh
   1.235 -before I became aware of the existence of the attachment system.
   1.236 -One could argue that this fact disqualifies my reading of the
   1.237 -documentation.
   1.238 -If I would have installed nmh from source back then, I could agree.
   1.239 -Yet I had used a prepackaged version and had expected that it would
   1.240 -just work.
   1.241 +.LP
   1.242 +Unfortunately, the attachment system,
   1.243 +like any new facilities in nmh,
   1.244 +was deactive by default.
   1.245  .P
   1.246  During my work in Argentina, I tried to improve the attachment system.
   1.247 -Because of great opposition in the nmh community, after long discussions,
   1.248 -my patch died as a proposal on the mailing list.
   1.249 +But, because of great opposition in the nmh community,
   1.250 +my patch died as a proposal on the mailing list, after long discussions.
   1.251  .[
   1.252  nmh-workers attachment proposal
   1.253  .]
   1.254 -In Januar 2012, I applied the patch in an extended form to mmh.
   1.255 +In Januar 2012, I extended the patch and applied it to mmh.
   1.256  .Ci 8ff284ff9167eff8f5349481529332d59ed913b1
   1.257 +In mmh, the attachment system is active by default.
   1.258 +Instead of command line switches, the
   1.259 +.Pe Attachment-Header
   1.260 +profile entry is used to specify
   1.261 +the name of the attachment header field.
   1.262 +It is pre-defined to
   1.263 +.Hd Attach .
   1.264  .P
   1.265 -In mmh, the attachment system is active by default.
   1.266 -There are no command line switches anymore, but a pre-defined attachment
   1.267 -header field.
   1.268 -It is named
   1.269 -.Hd Attach
   1.270 -by default, but can be renamed with the
   1.271 -.Pe Attachment-Header
   1.272 -profile entry.
   1.273  To add an attachment to a draft, simply add an attachment header:
   1.274  .VS
   1.275  To: bob
   1.276 @@ -1962,20 +1930,21 @@
   1.277  Here it is.
   1.278  VE
   1.279  The header field can be added to the draft manually in the editor,
   1.280 -by using the `attach' command at the WhatNow prompt, or with
   1.281 +or by using the `attach' command at the WhatNow prompt, or
   1.282 +non-interactively with
   1.283  .Pn anno :
   1.284  .VS
   1.285 -anno -append -nodate -component Attach -text /path/to/file
   1.286 +anno -append -nodate -component Attach -text /path/to/attachment
   1.287  VE
   1.288 -Drafts with attachment headers are converted to MIME automatically
   1.289 -on sending.
   1.290 -The draft stored in the draft folder is always in source form with
   1.291 +Drafts with attachment headers are converted to MIME automatically by
   1.292 +.Pn send .
   1.293 +The conversion to MIME is invisible to the user.
   1.294 +The draft stored in the draft folder is always in source form, with
   1.295  attachment headers.
   1.296 -The convertion to MIME is done invisible to the user.
   1.297  If the MIMEification fails, for instance because the file to attach
   1.298  is not accessible, the original draft is not changed.
   1.299  .P
   1.300 -Forwarding message is handled by the same attachment system.
   1.301 +The attachment system handles the forwarding of messages, too.
   1.302  If the attachment header value starts with a plus character (`+'),
   1.303  like in
   1.304  .Cl "Attach: +bob 30 42" ,
   1.305 @@ -1986,58 +1955,128 @@
   1.306  .P
   1.307  Closely related to attachments is non-ASCII text content,
   1.308  because it requires MIME too.
   1.309 -In nmh it the user needed to invoke `mime' at the WhatNow prompt
   1.310 +In nmh, the user needed to call `mime' at the WhatNow prompt
   1.311  to have the draft converted to MIME.
   1.312 -This was necessary if the draft contained non-ASCII characters.
   1.313 +This was necessary whenever the draft contained non-ASCII characters.
   1.314  If the user did not call `mime', a broken message would be sent.
   1.315  Therefore, the
   1.316  .Pe automimeproc
   1.317  profile entry could be specified to have the `mime' command invoked
   1.318 -automatically for each message.
   1.319 +automatically each time.
   1.320  Unfortunately, this approach conflicted with with attachment system
   1.321  because the draft would already be in MIME format at the time
   1.322  when the attachment system wanted to MIMEify it.
   1.323 -To use the attachment system, the user must not run `mime' at the
   1.324 -WhatNow prompt nor have
   1.325 +To use nmh's attachment system, `mime' must not be called at the
   1.326 +WhatNow prompt and
   1.327  .Pe automimeproc
   1.328 -set in the profile.
   1.329 +must not be set in the profile.
   1.330  But then the case of non-ASCII text without attachment headers was
   1.331  not caught.
   1.332 -All in all a bad solution.
   1.333 -My patch from December 2010 already solved this situation.
   1.334 +All in all, the solution was complex and irritating.
   1.335 +My patch from December 2010 would have simplified the situation.
   1.336 +.P
   1.337  Mmh's current solution is even more elaborate.
   1.338  Any necessary MIMEification is done automatically.
   1.339  There is no `mime' command at the WhatNow prompt anymore.
   1.340 -The draft will be converted to MIME when either an attachment header
   1.341 -or non-ASCII text is present.
   1.342 +The draft will be converted automatically to MIME when either an
   1.343 +attachment header or non-ASCII text is present.
   1.344  Further more, the special meaning of the hash character (`#')
   1.345 -at the beginning of the line in the draft message is removed.
   1.346 -The user needs not at all deal about the topic.
   1.347 +at line beginnings in the draft message is removed.
   1.348 +Users need not at all deal with the whole topic.
   1.349  .P
   1.350 -This improvement has a price: The new approach does not directly
   1.351 -support arbitrary MIME compositions.
   1.352 -Nonetheless, the full power of
   1.353 +Although the new approach does not anymore support arbitrary MIME
   1.354 +compositions directly, the full power of
   1.355  .Pn mhbuild
   1.356  can still be accessed.
   1.357 -As long as no attachment headers are included, the user can create a
   1.358 -nonlimited
   1.359 +Given no attachment headers are included, the user can create
   1.360  .Pn mhbuild
   1.361 -composition draft like in nmh.
   1.362 +composition drafts like in nmh.
   1.363  Then, at the WhatNow prompt, he needs to invoke
   1.364  .Cl "edit mhbuild
   1.365  to convert it to MIME.
   1.366 -Because the resulting draft does only contain ASCII characters
   1.367 -and has no attachment headers, the attachment system will not touch it.
   1.368 +Because the resulting draft does neither contain non-aASCII characters
   1.369 +nor has it attachment headers, the attachment system will not touch it.
   1.370  .P
   1.371  The approach taken in mmh is taylored towards todays most common case:
   1.372  a text part with possibly attachments.
   1.373 -Still, the full power of
   1.374 +This case is simplified a lot for users.
   1.375 +
   1.376 +.U3 "MIME Type Guessing
   1.377 +.P
   1.378 +The use of
   1.379  .Pn mhbuild
   1.380 -can be accessed with a bit of overhead.
   1.381 +composition drafts had one notable advantage over attachment headers
   1.382 +from the programmer's point of view: The user provides the appropriate
   1.383 +MIME types for files to include.
   1.384 +The attachment system needs to find out the correct MIME type itself.
   1.385 +This is a difficult task, yet it spares the user irritating work.
   1.386 +Determining the correct MIME type of content is partly mechanical,
   1.387 +partly intelligent work.
   1.388 +Forcing the user to find out the correct MIME type,
   1.389 +forces him to do partly mechanical work.
   1.390 +Letting the computer do the work, can lead to bad choices for difficult
   1.391 +content.
   1.392 +For mmh, the latter option was chosen.
   1.393 +.P
   1.394 +Determining the MIME type by the suffix of the file name is a dumb
   1.395 +approach, yet it is simple to implement and provides good results
   1.396 +for the common cases.
   1.397 +Mmh implements this approach in the
   1.398 +.Pn print-mimetype
   1.399 +script.
   1.400 +Using it is the default choice.
   1.401 +.P
   1.402 +A far better but less portable approach is the use of
   1.403 +.Pn file .
   1.404 +This standard tool tries to determine the type of files.
   1.405 +Unfortunately, its capabilities and accuracy varies from system to system.
   1.406 +Additionally, its output was only intended for human beings,
   1.407 +but not to be used by programs.
   1.408 +It varies much.
   1.409 +Nevertheless, modern versions of GNU
   1.410 +.Pn file ,
   1.411 +which is prevalent on the popular GNU/Linux systems,
   1.412 +provides MIME type output in machine-readable form.
   1.413 +Although this solution is highly system-dependent,
   1.414 +it solves the difficult problem well.
   1.415 +On systems where GNU
   1.416 +.Pn file ,
   1.417 +version 5.04 or higher, is available it should be used.
   1.418 +One needs to specify the following profile entry to do so:
   1.419 +.VS
   1.420 +Mime-Type-Query: file -b --mime
   1.421 +VE
   1.422 +.LP
   1.423 +Other versions of
   1.424 +.Pn file
   1.425 +might possibly be usable with wrapper scripts to reformat the output.
   1.426 +The diversity among
   1.427 +.Pn file
   1.428 +implementations is great; one needs to check the local variant.
   1.429 +.P
   1.430 +If no MIME type can be determined, text content gets sent as
   1.431 +`text/plain' and anything else under the generic fall-back type
   1.432 +`application/octet-stream'.
   1.433 +It is not possible in mmh to override the automatic MIME type guessing
   1.434 +for a specific file.
   1.435 +To do so, the user would need to know in advance for which file
   1.436 +the automatic guessing does fail, or the system would require interaction.
   1.437 +I consider both cases impractical.
   1.438 +The existing solution should be sufficient.
   1.439 +If not, the user may always fall back to
   1.440 +.Pn mhbuild
   1.441 +composition drafts and ignore the attachment system.
   1.442  
   1.443 -.\" XXX: MIME types
   1.444 -.\" XXX: whatnow prompt commands
   1.445 -.\" XXX: anno rework
   1.446 +
   1.447 +.U3 "Storing Attachments
   1.448 +.P
   1.449 +FIXME
   1.450 +
   1.451 +
   1.452 +.U3 "Showing MIME Messages
   1.453 +.P
   1.454 +FIXME
   1.455 +
   1.456  
   1.457  
   1.458  .H2 "Digital Cryptography
   1.459 @@ -2045,10 +2084,16 @@
   1.460  Signing and encryption.
   1.461  
   1.462  
   1.463 -.H2 "Good Defaults
   1.464 +
   1.465 +.H2 "Modern Defaults
   1.466  .P
   1.467 -foo
   1.468 -
   1.469 +Just to give one example, for me it took one year of using nmh
   1.470 +before I became aware of the existence of the attachment system.
   1.471 +One could argue that this fact disqualifies my reading of the
   1.472 +documentation.
   1.473 +If I would have installed nmh from source back then, I could agree.
   1.474 +Yet I had used a prepackaged version and had expected that it would
   1.475 +just work.
   1.476  
   1.477  
   1.478  
   1.479 @@ -2061,6 +2106,36 @@
   1.480  .P
   1.481  POSIX
   1.482  
   1.483 +.U3 "Converting to Standard Code
   1.484 +.P
   1.485 +One part of this task was converting obsolete code constructs
   1.486 +to standard constructs.
   1.487 +As I'm not even thirty years old and have no more than seven years of
   1.488 +Unix experience, I needed to learn about the history in retrospective.
   1.489 +Older people likely have used those ancient constructs themselves
   1.490 +and have suffered from their incompatibilities and have longed for
   1.491 +standardization.
   1.492 +Unfortunately, I have only read that others had done so.
   1.493 +This put me in a much more difficult positions when working on the old
   1.494 +code.
   1.495 +I needed to recherche what other would have known by heart from
   1.496 +experience.
   1.497 +All my programming experience comes from a time past ANSI C
   1.498 +and past POSIX.
   1.499 +Although I knew about the times before, I took the
   1.500 +current state implicitly for granted most of the time.
   1.501 +.P
   1.502 +Being aware of
   1.503 +these facts, I rather let people with more historic experience solve the 
   1.504 +task of converting the ancient code constructs to standardized ones.
   1.505 +Luckily, Lyndon Nerenberg focused on this task at the nmh project.
   1.506 +He converted large parts of the code to POSIX constructs, removing
   1.507 +the conditionals compilation for now standardized features.
   1.508 +I'm thankful for this task being solved. I only pulled the changes into
   1.509 +mmh.
   1.510 +
   1.511 +
   1.512 +
   1.513  
   1.514  .H2 "Separation
   1.515  
   1.516 @@ -2171,6 +2246,9 @@
   1.517  .P
   1.518  Code layout, goto, ...
   1.519  
   1.520 +.P
   1.521 +anno rework
   1.522 +
   1.523  
   1.524  
   1.525