1.1 --- a/discussion.roff	Sat Jul 14 23:19:27 2012 +0200
     1.2 +++ b/discussion.roff	Sun Jul 15 18:41:35 2012 +0200
     1.3 @@ -461,6 +461,7 @@
     1.4  conflicts with the basic concept of MH.
     1.5  These two tools might still be useful, but they should not be part of mmh.
     1.6  .P
     1.7 +.Id slocal
     1.8  Finally, there is
     1.9  .Pn slocal ,
    1.10  which is an MDA and thus not directly MUA-related.
    1.11 @@ -3407,12 +3408,13 @@
    1.12  
    1.13  .H2 "Profile Reading
    1.14  .P
    1.15 -The MH profile contains the configuration for the user-specific MH setup.
    1.16 -MH tools read the profile right after starting up,
    1.17 -as it contains the location of the user's mail storage
    1.18 +The MH profile contains the configuration of a user-specific MH setup.
    1.19 +MH tools read the profile right after starting up
    1.20 +because it contains the location of the user's mail storage
    1.21  and similar settings that influence the whole setup.
    1.22 -Furthermore, the profile contains the default switches for the tools,
    1.23 -hence, it must be read before the command line switches are processed.
    1.24 +Furthermore, the profile contains the default switches for the tools
    1.25 +as well.
    1.26 +The context file is read along with the profile.
    1.27  .P
    1.28  For historic reasons, some MH tools did not read the profile and context.
    1.29  Among them were
    1.30 @@ -3422,11 +3424,12 @@
    1.31  and
    1.32  .Pn slocal .
    1.33  The reason why these tools ignored the profile were not clearly stated.
    1.34 -During the discussion on the nmh-workers mailing list,
    1.35 +During a discussion on the nmh-workers mailing list,
    1.36  David Levine posted an explanation, quoting John Romine:
    1.37  .[
    1.38  nmh-workers levine post profile
    1.39  .]
    1.40 +
    1.41  .QS
    1.42  I asked John Romine and here's what he had to say, which
    1.43  agrees and provides an example that convinces me:
    1.44 @@ -3458,14 +3461,16 @@
    1.45  .Pn whatnow
    1.46  do this).
    1.47  .QE
    1.48 +.sp \n(PDu
    1.49  I think that's the way to go.
    1.50  My personal preference is to use a command line option,
    1.51  not an environment variable.
    1.52  .QE
    1.53 +
    1.54  .P
    1.55 -To solve the problem of
    1.56 +To solve the problem that
    1.57  .Pn post
    1.58 -not honoring the
    1.59 +does not honor the
    1.60  .Pe fileproc
    1.61  profile entry,
    1.62  the community roughly agreed that a switch
    1.63 @@ -3475,50 +3480,50 @@
    1.64  to be able to pass a different fileproc.
    1.65  I strongly disagree with this approach because it does not solve
    1.66  the problem; it only removes a single symptom.
    1.67 -The problem is that
    1.68 +The actual problem is that
    1.69  .Pn post
    1.70 -does not behave as expected.
    1.71 -But all programs should behave as expected.
    1.72 -Clear and simple concepts are a precondition for this.
    1.73 -Hence, the real solution is having all MH tools read the profile.
    1.74 +does not behave as expected,
    1.75 +though all programs should behave as expected.
    1.76 +Clear and general concepts are a precondition for this.
    1.77 +Thus, there should be no separation into ``front-end UI programs''
    1.78 +and ones that ``should not be called by users directly''.
    1.79 +The real solution is having all MH tools read the profile.
    1.80  .P
    1.81 -The problem has a further aspect.
    1.82 -It mainly originates in
    1.83 -.Pn mhmail .
    1.84 +But the problem has a further aspect,
    1.85 +which originates from
    1.86 +.Pn mhmail
    1.87 +mainly.
    1.88  .Pn mhmail
    1.89  was intended to be a replacement for
    1.90  .Pn mailx
    1.91  on systems with MH installations.
    1.92 +In difference to
    1.93 +.Pn mailx ,
    1.94  .Pn mhmail
    1.95 -should have been able to use just like
    1.96 -.Pn mailx ,
    1.97 -but sending the message via MH's
    1.98 +used MH's
    1.99  .Pn post
   1.100 -instead of
   1.101 -.Pn sendmail .
   1.102 -Using
   1.103 +to send the message.
   1.104 +The idea was that using
   1.105  .Pn mhmail
   1.106 -should not be influenced by the question whether the user had
   1.107 +should not be influenced whether the user had
   1.108  MH set up for himself or not.
   1.109 +Therefore
   1.110  .Pn mhmail
   1.111 -did not read the profile as this requests the user to set up MH
   1.112 -if not done yet.
   1.113 +had not read the profile.
   1.114  As
   1.115  .Pn mhmail
   1.116  used
   1.117  .Pn post ,
   1.118  .Pn post
   1.119 -could not read the profile neither.
   1.120 -This is the reason why
   1.121 -.Pn post
   1.122 -does not read the profile.
   1.123 +was not allowed to read the profile neither.
   1.124  This is the reason for the actual problem.
   1.125 -It was not much of a problem because
   1.126 +Yet, this was not considered much of a problem because
   1.127  .Pn post
   1.128  was not intended to be used by users directly.
   1.129 +To invoke
   1.130 +.Pn post ,
   1.131  .Pn send
   1.132 -is the interactive front-end to
   1.133 -.Pn post .
   1.134 +was used an a front-end.
   1.135  .Pn send
   1.136  read the profile and passed all relevant values on the command line to
   1.137  .Pn post
   1.138 @@ -3526,23 +3531,76 @@
   1.139  .P
   1.140  The important insight is that
   1.141  .Pn mhmail
   1.142 -is no true MH tool.
   1.143 -The concepts broke because this outlandish tool was treated as any other
   1.144 -MH tool.
   1.145 +is a wolf in sheep's clothing.
   1.146 +This alien tool broke the concepts because it was treated like
   1.147 +a normal MH tool.
   1.148  Instead it should have been treated accordingly to its foreign style.
   1.149 -The solution is not to prevent the tools reading the profile but
   1.150 -to instruct them reading a different profile.
   1.151 +.P
   1.152 +The solution is not to prevent the tools from reading the profile but
   1.153 +to instruct them to read a different profile.
   1.154  .Pn mhmail
   1.155 -could have set up a well-defined profile and caused all MH tools
   1.156 -in the session to use it by exporting an environment variable.
   1.157 -With this approach, no special cases would have been introduced,
   1.158 -no surprises would have been caused.
   1.159 -By writing a clean-profile-wrapper, the concept could have been
   1.160 -generalized orthogonally to the whole MH tool chest.
   1.161 -Then Rose's motivation behind the decision that
   1.162 +could have set up a well-defined profile and caused the following
   1.163  .Pn post
   1.164 -ignores the profile, as quoted by Jeffrey Honig,
   1.165 -would have become possible:
   1.166 +to use this profile by exporting an environment variable.
   1.167 +With this approach, no special cases would have been introduced
   1.168 +and no surprises would have been caused.
   1.169 +By writing a wrapper program to provide a clean temporary profile,
   1.170 +the concept could have been generalized orthogonally to the whole
   1.171 +MH tool chest.
   1.172 +.P
   1.173 +In mmh, the wish to have
   1.174 +.Pn mhmail
   1.175 +as a replacement for
   1.176 +.Pn mailx
   1.177 +is considered obsolete.
   1.178 +Mmh's
   1.179 +.Pn mhmail
   1.180 +does no longer cover this use-case
   1.181 +.Ci d36e56e695fe1c482c7920644bfbb6386ac9edb0 .
   1.182 +Currently,
   1.183 +.Pn mhmail
   1.184 +is in a transition state
   1.185 +.Ci 32d4f9daaa70519be3072479232ff7be0500d009 .
   1.186 +It may become a front-end to
   1.187 +.Pn comp ,
   1.188 +which provides an alternative interface which can be more convenient
   1.189 +in some cases.
   1.190 +This would convert
   1.191 +.Pn mhmail
   1.192 +into an ordinary MH tool.
   1.193 +If, however, this idea does not convince, then
   1.194 +.Pn mhmail
   1.195 +will be removed.
   1.196 +.P
   1.197 +In the mmh tool chest, every program reads the profile.
   1.198 +(\c
   1.199 +.Pn slocal
   1.200 +is not considered part of the mmh tool chest (cf. Sec.
   1.201 +.Cf slocal ).)
   1.202 +Mmh has no
   1.203 +.Pn post
   1.204 +program, but it has
   1.205 +.Pn spost ,
   1.206 +which now does read the profile
   1.207 +.Ci 3e017a7abbdf69bf0dff7a4073275961eda1ded8 .
   1.208 +Following this change,
   1.209 +.Pn send
   1.210 +and
   1.211 +.Pn spost
   1.212 +can be considered for merging.
   1.213 +Besides
   1.214 +.Pn send ,
   1.215 +.Pn spost
   1.216 +is only invoked directly by the to-be-changed
   1.217 +.Pn mhmail
   1.218 +implementation and by
   1.219 +.Pn rcvdist ,
   1.220 +which requires rework anyway.
   1.221 +
   1.222 +.P
   1.223 +Jeffrey Honig quoted Marshall T. Rose explaining the decision that
   1.224 +.Pn post
   1.225 +ignores the profile:
   1.226  .[
   1.227  nmh-workers honig post profile
   1.228  .]
   1.229 @@ -3552,62 +3610,18 @@
   1.230  when you run a command by hand, then you want your own defaults...
   1.231  .QE
   1.232  .LP
   1.233 -Yet, I consider this explanation shortsighted.
   1.234 -We should rather regard theses two cases as just two different MH setups,
   1.235 -based on two different profiles.
   1.236 -Mapping such problems on the concepts of switching between different
   1.237 -profiles, solves them once for all.
   1.238 -.P
   1.239 -In mmh, the wish to have
   1.240 -.Pn mhmail
   1.241 -as a replacement for
   1.242 -.Pn mailx
   1.243 -is considered obsolete.
   1.244 -Mmh's
   1.245 -.Pn mhmail
   1.246 -does no longer cover this use-case.
   1.247 -Currently,
   1.248 -.Pn mhmail
   1.249 -is in a transition state.
   1.250 -.Ci 32d4f9daaa70519be3072479232ff7be0500d009
   1.251 -It may become a front-end to
   1.252 -.Pn comp ,
   1.253 -which provides an interface more convenient in some cases.
   1.254 -In this case,
   1.255 -.Pn mhmail
   1.256 -will become an ordinary MH tool, reading the profile.
   1.257 -If, however, this idea will not convince, then
   1.258 -.Pn mhmail
   1.259 -will be removed.
   1.260 -.P
   1.261 -Every program in the mmh tool chest reads the profile.
   1.262 -The only exception is
   1.263 -.Pn slocal ,
   1.264 -which is not considered part of the mmh tool chest.
   1.265 -This MDA is only distributed with mmh, currently.
   1.266 -Mmh has no
   1.267 -.Pn post
   1.268 -program, but
   1.269 -.Pn spost ,
   1.270 -which now reads the profile.
   1.271 -.Ci 3e017a7abbdf69bf0dff7a4073275961eda1ded8
   1.272 -With this change,
   1.273 -.Pn send
   1.274 -and
   1.275 -.Pn spost
   1.276 -can be considered to be merged.
   1.277 -.Pn spost
   1.278 -is only invoked directly by the to-be-changed
   1.279 -.Pn mhmail
   1.280 -implementation and by
   1.281 -.Pn rcvdist ,
   1.282 -which will require rework.
   1.283 -.P
   1.284 -The
   1.285 -.Fu context_foil()
   1.286 -function to pretend to have read an empty profile was removed.
   1.287 -.Ci 68af8da96bea87a5541988870130b6209ce396f6
   1.288 -All mmh tools read the profile.
   1.289 +The explanation neither matches the problem concered exactly
   1.290 +nor is the interpretation clear.
   1.291 +If the described desire addresses the technical level,
   1.292 +then it conflicts fundametally with the Unix philosophy,
   1.293 +precisely because the indistinquishability of human and script
   1.294 +input is the main reason for the huge software leverage in Unix.
   1.295 +If, however, the described desire addresses the user's view,
   1.296 +then different technical solutions are more appropriate.
   1.297 +The two cases can be regarded simply as two different MH setups.
   1.298 +Hence, mapping the problem of different behavior between interactive and
   1.299 +automated use on the concept of switching between different profiles,
   1.300 +marks it already solved.
   1.301  
   1.302  
   1.303  
   1.304 @@ -3615,89 +3629,89 @@
   1.305  .P
   1.306  MH is one decade older than the POSIX and ANSI C standards.
   1.307  Hence, MH included own implementations of functions
   1.308 -that are standardized and thus widely available today,
   1.309 -but were not back then.
   1.310 -Today, twenty years after the POSIX and ANSI C were published,
   1.311 -developers can expect systems to comply with these standards.
   1.312 +that were neither standardized nor widely available, back then.
   1.313 +Today, twenty years after POSIX and ANSI C were published,
   1.314 +developers can expect that systems comply with these standards.
   1.315  In consequence, MH-specific replacements for standard functions
   1.316  can and should be dropped.
   1.317 -Kernighan and Pike advise: ``Use standard libraries.''
   1.318 +Kernighan and Pike advise: ``Use standard libraries''.
   1.319  .[ [
   1.320  kernighan pike practice of programming
   1.321  .], p. 196]
   1.322  Actually, MH had followed this advice in history,
   1.323 -but it had not adjusted to the changes in this field.
   1.324 +but it had not adjusted to more recent changes in this field.
   1.325  The
   1.326  .Fu snprintf()
   1.327  function, for instance, was standardized with C99 and is available
   1.328  almost everywhere because of its high usefulness.
   1.329 -The project's own implementation of
   1.330 +Thus, the project's own implementation of
   1.331  .Fu snprintf()
   1.332  was dropped in March 2012 in favor for using the one of the
   1.333 -standard library.
   1.334 -.Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32
   1.335 +standard library
   1.336 +.Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32 .
   1.337  Such decisions limit the portability of mmh
   1.338  if systems do not support these standardized and widespread functions.
   1.339  This compromise is made because mmh focuses on the future.
   1.340  .P
   1.341  .\" XXX kuerzen und mit dem naechsten Absatz vereinen
   1.342 -I am still in my twenties and my C and Unix experience comprises
   1.343 -only half a dozen years.
   1.344 -Hence, I need to learn about the history in retrospective.
   1.345 -I have not used those ancient constructs myself.
   1.346 -I have not suffered from their incompatibilities.
   1.347 +As I am still in my twenties, have no programming experience from
   1.348 +past decades.
   1.349 +I have not followed the evolution of C through time.
   1.350 +I have not suffered from the the Unix wars.
   1.351  I have not longed for standardization.
   1.352  All my programming experience is from a time when ANSI C and POSIX
   1.353  were well established already.
   1.354 +Thus, I needed to learn about the history in retrospective.
   1.355  I have only read a lot of books about the (good) old times.
   1.356 -This puts me in a difficult position when working with old code.
   1.357 +This put me in a difficult position when working with old code.
   1.358  I need to freshly acquire knowledge about old code constructs and ancient
   1.359  programming styles, whereas older programmers know these things by
   1.360  heart from their own experience.
   1.361 -.P
   1.362  Being aware of the situation, I rather let people with more historic
   1.363 -experience replace ancient code constructs with standardized ones.
   1.364 +experience do the transition from ancient code constructs to
   1.365 +standardized ones.
   1.366  Lyndon Nerenberg covered large parts of this task for the nmh project.
   1.367  He converted project-specific functions to POSIX replacements,
   1.368  also removing the conditionals compilation of now standardized features.
   1.369 -Ken Hornstein and David Levine had their part in the work, too.
   1.370 -Often, I only needed to pull over changes from nmh into mmh.
   1.371 -These changes include many commits; these are among them:
   1.372 +Ken Hornstein and David Levine had their part in this work, as well.
   1.373 +Often, I only pulled the changes over from nmh into mmh.
   1.374 +These changes include many commits, among them:
   1.375  .Ci 768b5edd9623b7238e12ec8dfc409b82a1ed9e2d
   1.376  .Ci 0052f1024deb0a0a2fc2e5bacf93d45a5a9c9b32 .
   1.377  .P
   1.378 -During my own work, I tidied up the \fIMH standard library\fP,
   1.379 -.Fn libmh.a ,
   1.380 -which is located in the
   1.381 +Nevertheless, I worked on the task as well, tidying up the
   1.382 +\fIMH standard library\fP,
   1.383 +.Fn libmh.a .
   1.384 +It is located in the
   1.385  .Fn sbr
   1.386 -(``subroutines'') directory in the source tree.
   1.387 -The MH library includes functions that mmh tools usually need.
   1.388 +(``subroutines'') directory in the source tree and
   1.389 +includes functions that mmh tools usually need.
   1.390  Among them are MH-specific functions for profile, context, sequence,
   1.391  and folder handling, but as well
   1.392  MH-independent functions, such as auxiliary string functions,
   1.393  portability interfaces and error-checking wrappers for critical
   1.394  functions of the standard library.
   1.395 -.P
   1.396 +.BU
   1.397  I have replaced the
   1.398  .Fu atooi()
   1.399  function with calls to
   1.400 +.Fu strtoul() ,
   1.401 +setting the third parameter, the base, to eight.
   1.402  .Fu strtoul()
   1.403 -with the third parameter, the base, set to eight.
   1.404 -.Fu strtoul()
   1.405 -is part of C89 and thus considered safe to use.
   1.406 -.Ci c490c51b3c0f8871b6953bd0c74551404f840a74
   1.407 -.P
   1.408 +is part of C89 and thus considered safe to use
   1.409 +.Ci c490c51b3c0f8871b6953bd0c74551404f840a74 .
   1.410 +.BU
   1.411  I did remove project-included fallback implementations of
   1.412  .Fu memmove()
   1.413  and
   1.414 -.Fu strerror() ,
   1.415 +.Fu strerror()
   1.416 +.Ci b067ff5c465a5d243ce5a19e562085a9a1a97215 ,
   1.417  although Peter Maydell had re-included them into nmh in 2008
   1.418  to support SunOS 4.
   1.419  Nevertheless, these functions are part of ANSI C.
   1.420  Systems that do not even provide full ANSI C support should not
   1.421  put a load on mmh.
   1.422 -.Ci b067ff5c465a5d243ce5a19e562085a9a1a97215
   1.423 -.P
   1.424 +.BU
   1.425  The
   1.426  .Fu copy()
   1.427  function copies the string in parameter one to the location in
   1.428 @@ -3718,9 +3732,9 @@
   1.429  .Fu copy()
   1.430  was moved into the source file of
   1.431  .Fu concat()
   1.432 -and its visibility is now limited to it.
   1.433 -.Ci 552fd7253e5ee9e554c5c7a8248a6322aa4363bb
   1.434 -.P
   1.435 +and its visibility it limited to that
   1.436 +.Ci 552fd7253e5ee9e554c5c7a8248a6322aa4363bb .
   1.437 +.BU
   1.438  The function
   1.439  .Fu r1bindex()
   1.440  had been a generalized version of
   1.441 @@ -3728,7 +3742,7 @@
   1.442  with minor differences.
   1.443  As all calls to
   1.444  .Fu r1bindex()
   1.445 -had the slash (`/') as delimiter anyway,
   1.446 +had the slash (`\fL/\fP') as delimiter anyway,
   1.447  replacing
   1.448  .Fu r1bindex()
   1.449  with the more specific and better-named function
   1.450 @@ -3743,23 +3757,24 @@
   1.451  .Fu r1bindex()
   1.452  was kept but renamed to
   1.453  .Fu mhbasename() ,
   1.454 -fixing the delimiter to the slash.
   1.455 -.Ci 240013872c392fe644bd4f79382d9f5314b4ea60
   1.456 +setting the delimiter to the slash
   1.457 +.Ci 240013872c392fe644bd4f79382d9f5314b4ea60 .
   1.458  For possible uses of
   1.459  .Fu r1bindex()
   1.460  with a different delimiter,
   1.461  the ANSI C function
   1.462  .Fu strrchr()
   1.463  provides the core functionality.
   1.464 -.P
   1.465 +.BU
   1.466  The
   1.467  .Fu ssequal()
   1.468  function \(en apparently for ``substring equal'' \(en
   1.469  was renamed to
   1.470  .Fu isprefix() ,
   1.471 -because this is what it actually checks.
   1.472 -.Ci c20b4fa14515c7ab388ce35411d89a7a92300711
   1.473 -Its source file had included the following comments, no joke.
   1.474 +because this is what it actually checked
   1.475 +.Ci c20b4fa14515c7ab388ce35411d89a7a92300711.
   1.476 +Its source file had included both of the following comments, no joke.
   1.477 +.in -\n(PIu
   1.478  .VS
   1.479  /*
   1.480   * THIS CODE DOES NOT WORK AS ADVERTISED.
   1.481 @@ -3774,9 +3789,10 @@
   1.482   * If yes, then return 1, else return 0.
   1.483   */
   1.484  VE
   1.485 -Two months later, it was completely removed by replacing it with
   1.486 -.Fu strncmp() .
   1.487 -.Ci b0b1dd37ff515578cf7cba51625189eb34a196cb
   1.488 +.in +\n(PIu
   1.489 +Eventually, the function was completely replaced with calls to
   1.490 +.Fu strncmp()
   1.491 +.Ci b0b1dd37ff515578cf7cba51625189eb34a196cb .
   1.492  
   1.493  
   1.494  
   1.495 @@ -3792,96 +3808,91 @@
   1.496  It also contains the location of the MH directory in the profile entry
   1.497  .Pe Path .
   1.498  The MH directory contains the mail storage and is the first
   1.499 -place to search for personal forms, scan formats, and similar
   1.500 +place to search for form files, scan formats, and similar
   1.501  configuration files.
   1.502  The location of the MH directory can be chosen freely by the user.
   1.503 -The default and usual name is a directory named
   1.504 +The usual name is a directory named
   1.505  .Fn Mail
   1.506 -in the home directory.
   1.507 +in the user's home directory.
   1.508  .P
   1.509  The way MH data is split between profile and MH directory is a legacy.
   1.510  It is only sensible in a situation where the profile is the only
   1.511  configuration file.
   1.512  Why else should the mail storage and the configuration files be intermixed?
   1.513 -They are different kinds of data:
   1.514 -The data to be operated on and the configuration to change how
   1.515 -tools operate.
   1.516 -.\" XXX bad ... inapropriate?
   1.517 +They are of different kind:
   1.518 +One kind is the data to be operated on and the other kind is
   1.519 +the configuration to change how tools operate.
   1.520  Splitting the configuration between the profile and the MH directory
   1.521 -is bad.
   1.522 -Merging the mail storage and the configuration in one directory is bad
   1.523 -as well.
   1.524 -As the mail storage and the configuration were not separated sensibly
   1.525 -in the first place, I did it now.
   1.526 +is inappropriate, as well.
   1.527 +I improved the situation by breaking compatibility.
   1.528  .P
   1.529 -Personal mmh data is grouped by type, resulting in two distinct parts:
   1.530 +In mmh, personal data is grouped by type.
   1.531 +This results in two distinct parts:
   1.532  the mail storage and the configuration.
   1.533 -In mmh, the mail storage directory still contains all the messages,
   1.534 +The mail storage directory still contains all the messages,
   1.535  but, in exception of public sequences files, nothing else.
   1.536  In difference to nmh, the auxiliary configuration files are no longer
   1.537  located there.
   1.538  Therefore, the directory is no longer called the user's \fIMH directory\fP
   1.539 -but his \fImail storage\fP.
   1.540 +but the user's \fImail storage\fP.
   1.541  Its location is still user-chosen, with the default name
   1.542 -.Fn Mail ,
   1.543 +.Fn Mail
   1.544  in the user's home directory.
   1.545 -In mmh, the configuration is grouped together in
   1.546 -the hidden directory
   1.547 +The configuration is grouped together in the hidden directory
   1.548  .Fn \&.mmh
   1.549  in the user's home directory.
   1.550  This \fImmh directory\fP contains the context file, personal forms,
   1.551  scan formats, and the like, but also the user's profile, now named
   1.552  .Fn profile .
   1.553 -The location of the profile is no longer fixed to
   1.554 +The path to the profile is no longer
   1.555  .Fn $HOME/.mh_profile
   1.556 -but to
   1.557 +but
   1.558  .Fn $HOME/.mmh/profile .
   1.559 -Having both the file
   1.560 +(The alternative of having file
   1.561  .Fn $HOME/.mh_profile
   1.562 -and the configuration directory
   1.563 +and a configuration directory
   1.564  .Fn $HOME/.mmh
   1.565 -appeared to be inconsistent.
   1.566 +appeared to be inconsistent.)
   1.567 +.P
   1.568  The approach chosen for mmh is consistent, simple, and familiar to
   1.569  Unix users.
   1.570 +The main achievement of the change is the clear and sensible separation
   1.571 +of the mail storage and the configuration.
   1.572  .Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b
   1.573  .P
   1.574 -MH allows users to have multiple MH setups.
   1.575 -Therefore, it is necessary to select a different profile.
   1.576 +As MH allows users to have multiple MH setups,
   1.577 +it is necessary to switch the profile.
   1.578  The profile is the single entry point to access the rest of a
   1.579  personal MH setup.
   1.580  In nmh, the environment variable
   1.581  .Ev MH
   1.582 -could be used to specify a different profile.
   1.583 -To operate in the same MH setup with a separate context,
   1.584 -the
   1.585 +is used to specify a different profile.
   1.586 +To operate in the same MH setup with a separate context, the
   1.587  .Ev MHCONTEXT
   1.588 -environment variable could be used.
   1.589 -This allows having own current folders and current messages in
   1.590 -each terminal, for instance.
   1.591 -In mmh, three environment variables are used.
   1.592 +environment variable is used.
   1.593 +This allows having a separate current folder in each terminal at
   1.594 +the same time, for instance.
   1.595 +In mmh, three environment variables replace the two of nmh.
   1.596  .Ev MMH
   1.597  overrides the default location of the mmh directory (\c
   1.598  .Fn .mmh ).
   1.599  .Ev MMHP
   1.600  and
   1.601  .Ev MMHC
   1.602 -override the paths to the profile and context files, respectively.
   1.603 +override the paths to the profile and context file, respectively.
   1.604  This approach allows the set of personal configuration files to be chosen
   1.605 -independently from the profile, context, and mail storage.
   1.606 -.Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b
   1.607 -.P
   1.608 -The separation of the files by type is sensible and convenient.
   1.609 +independently of the profile, context, and mail storage.
   1.610  The new approach has no functional disadvantages,
   1.611  as every setup I can imagine can be implemented with both approaches,
   1.612 -possibly even easier with the new approach.
   1.613 -The main achievement of the change is the clear and sensible split
   1.614 -between mail storage and configuration.
   1.615 +possibly even easier with the new one.
   1.616 +.Ci 7030d7edb099bff36ded7548bb5380f7acab4f9b
   1.617  
   1.618  
   1.619  
   1.620  
   1.621  
   1.622  .H2 "Modularization
   1.623 +.Id modularization
   1.624  .P
   1.625  The source code of the mmh tools is located in the
   1.626  .Fn uip
   1.627 @@ -3911,23 +3922,19 @@
   1.628  .\" XXX graph
   1.629  .P
   1.630  Splitting the source code of a large program into multiple files can
   1.631 -increase the readability of its source code.
   1.632 -.\" XXX however?
   1.633 -Most of the mmh tools are simple and straight-forward programs.
   1.634 -With the exception of the MIME handling tools,
   1.635 -.Pn pick
   1.636 -is the largest tool.
   1.637 -It contains 1\|037 lines of source code, excluding the MH library.
   1.638 -Only the MIME handling tools (\c
   1.639 +increase the readability of its source code,
   1.640 +but most of the mmh tools are small and straight-forward programs.
   1.641 +In exception of the MIME handling tools (i.e.
   1.642  .Pn mhbuild ,
   1.643  .Pn mhstore ,
   1.644  .Pn show ,
   1.645 -etc.)
   1.646 -are larger.
   1.647 -Splitting programs with less than 1\|000 lines of code into multiple
   1.648 -source files seldom leads to better readability.
   1.649 -For such tools, splitting makes sense
   1.650 -when parts of the code are reused in other programs,
   1.651 +etc.),
   1.652 +.Pn pick
   1.653 +is the only tool with more than one thousand lines of source code.
   1.654 +Splitting programs with less than one thousand lines of code into
   1.655 +multiple source files leads seldom to better readability.
   1.656 +For such tools, splitting still makes sense
   1.657 +when parts of the code are reused in other programs
   1.658  and the reused code fragment is (1) not general enough
   1.659  for including it in the MH library
   1.660  or (2) has dependencies on a library that only few programs need.
   1.661 @@ -3944,12 +3951,13 @@
   1.662  No other tools use the folder packing functions.
   1.663  As another example,
   1.664  .Fn uip/termsbr.c
   1.665 -provides termcap support, which requires linking with a termcap or
   1.666 -curses library.
   1.667 -Including
   1.668 +accesses terminal properties, which requires linking with the
   1.669 +\fItermcap\fP or a \fIcurses\fP library.
   1.670 +If
   1.671  .Fn uip/termsbr.c
   1.672 -into the MH library would require every program to be linked with
   1.673 -termcap or curses, although only few of the programs require it.
   1.674 +is included in the MH library, then every program needs to be linked
   1.675 +with termcap or curses, although only few of the programs use
   1.676 +the library.
   1.677  .P
   1.678  The task of MIME handling is complex enough that splitting its code
   1.679  into multiple source files improves the readability.
   1.680 @@ -3959,11 +3967,11 @@
   1.681  lines of code in summary.
   1.682  The main code file
   1.683  .Fn uip/mhstore.c
   1.684 -consists of 800 lines; the other 1\|700 lines of code are reused in
   1.685 +consists of 800 lines; the other 1\|700 lines are code reused in
   1.686  other MIME handling tools.
   1.687  It seems to be worthwhile to bundle the generic MIME handling code into
   1.688  a MH-MIME library, as a companion to the MH standard library.
   1.689 -This is left open for the future.
   1.690 +This is left to be done.
   1.691  .P
   1.692  The work already accomplished focussed on the non-MIME tools.
   1.693  The amount of code compiled into each program was reduced.
   1.694 @@ -3989,13 +3997,13 @@
   1.695  .Pn send ,
   1.696  and
   1.697  .Pn anno
   1.698 -were compiled into
   1.699 +were all compiled into
   1.700  .Pn comp .
   1.701  This saved the need to execute these programs with
   1.702 +the expensive system calls
   1.703  .Fu fork()
   1.704  and
   1.705 -.Fu exec() ,
   1.706 -two expensive system calls.
   1.707 +.Fu exec() .
   1.708  Whereas this approach improved the time performance,
   1.709  it interwove the source code.
   1.710  Core functionalities were not encapsulated into programs but into
   1.711 @@ -4016,59 +4024,23 @@
   1.712  When another pair of command line switches was added to
   1.713  .Pn anno ,
   1.714  a rather ugly hack was implemented to avoid adding another parameter
   1.715 -to the function.
   1.716 -.Ci d9b1d57351d104d7ec1a5621f090657dcce8cb7f
   1.717 +to the function
   1.718 +.Ci d9b1d57351d104d7ec1a5621f090657dcce8cb7f .
   1.719  .P
   1.720 -Separation simplifies the understanding of program code
   1.721 -because the area influenced by any particular statement is smaller.
   1.722 -The separating on the program-level is more strict than the separation
   1.723 -on the function level.
   1.724  In mmh, the relevant code of
   1.725  .Pn comp
   1.726  comprises the two files
   1.727  .Fn uip/comp.c
   1.728  and
   1.729  .Fn uip/whatnowproc.c ,
   1.730 -together 210 lines of code.
   1.731 -In nmh,
   1.732 +together 210 lines of code,
   1.733 +whereas in nmh,
   1.734  .Pn comp
   1.735  comprises six files with 2\|450 lines.
   1.736 -Not all of the code in these six files was actually used by
   1.737 +Not all of the code in these six files is actually used by
   1.738  .Pn comp ,
   1.739 -but the code reader needed to read all of the code first to know which
   1.740 -parts were used.
   1.741 -.P
   1.742 -As I have read a lot in the code base during the last two years,
   1.743 -I learned about the easy and the difficult parts.
   1.744 -Code is easy to understand if the influenced code area is small
   1.745 -and its boundaries are strictly defined.
   1.746 -Furthermore, the code needs to solve the problem in a straight-forward way.
   1.747 -.P
   1.748 -.\" XXX move this paragraph somewhere else?
   1.749 -Reading
   1.750 -.Pn rmm 's
   1.751 -source code in
   1.752 -.Fn uip/rmm.c
   1.753 -is my recommendation for a beginner's entry point into the code base of nmh.
   1.754 -The reasons are that the task of
   1.755 -.Pn rmm
   1.756 -is straight forward and it consists of one small source code file only,
   1.757 -yet its source includes code constructs typical for MH tools.
   1.758 -With the introduction of the trash folder in mmh,
   1.759 -.Pn rmm
   1.760 -became a bit more complex, because it invokes
   1.761 -.Pn refile .
   1.762 -Still, it is a good example for a simple tool with clear sources.
   1.763 -.P
   1.764 -Understanding
   1.765 -.Pn comp
   1.766 -.\" XXX kate fragen: more vs. as much
   1.767 -requires to read 210 lines of code in mmh, but ten times more in nmh.
   1.768 -Due to the aforementioned hack in
   1.769 -.Pn anno
   1.770 -to save the additional parameter, information passed through the program's
   1.771 -source base in obscure ways.
   1.772 -Thus, understanding
   1.773 +but the reader needed to read it all to know which parts are relevant.
   1.774 +Understanding nmh's
   1.775  .Pn comp ,
   1.776  required understanding the inner workings of
   1.777  .Fn uip/annosbr.c
   1.778 @@ -4077,15 +4049,33 @@
   1.779  to be examined.
   1.780  Not doing so is a leap of faith, assuming that the developers
   1.781  have avoided obscure programming techniques.
   1.782 -By separating the tools on the program-level, the boundaries are
   1.783 -clearly visible and technically enforced.
   1.784 -The interfaces are calls to
   1.785 +Here, it should be recalled that information passed in obscure ways
   1.786 +through the program's source base, due to the aforementioned hack
   1.787 +to save an additional parameter in nmh's
   1.788 +.Pn anno .
   1.789 +.P
   1.790 +In mmh, understanding
   1.791 +.Pn comp
   1.792 +requires to read only 210 lines of code to read, whereas the amount
   1.793 +is ten times more for nmh's
   1.794 +.Pn comp .
   1.795 +.P
   1.796 +By separating the tools on the program-level,
   1.797 +the boundaries are clearly visible, as the interfaces are calls to
   1.798  .Fu exec()
   1.799  rather than arbitrary function calls.
   1.800 +Additionally, this kind of separation is more strict because 
   1.801 +it is technically enforced by the operating system;
   1.802 +it can not be simply bypassed with global variables.
   1.803 +Good separation simplifies the understanding of program code
   1.804 +because the area influenced by any particular statement is small.
   1.805 +As I have read a lot in nmh's code base during the last two years,
   1.806 +I have learned about the easy and the difficult parts.
   1.807 +In my observation, the understanding of code is enormously eased
   1.808 +if the influenced area is small and clearly bounded.
   1.809  .P
   1.810 -But the real problem is another:
   1.811 +Yet, the real problem is another:
   1.812  Nmh violates the golden ``one tool, one job'' rule of the Unix philosophy.
   1.813 -.\" XXX ref
   1.814  Understanding
   1.815  .Pn comp
   1.816  requires understanding
   1.817 @@ -4094,11 +4084,13 @@
   1.818  .Fn uip/sendsbr.c
   1.819  because
   1.820  .Pn comp
   1.821 -does annotate and send messages.
   1.822 -In nmh, there surely exists the tool
   1.823 +annotates and sends messages.
   1.824 +In nmh, there surely exist the tools
   1.825 +.Pn anno
   1.826 +and
   1.827  .Pn send ,
   1.828 -which does mainly send messages.
   1.829 -But
   1.830 +which cover these jobs,
   1.831 +but
   1.832  .Pn comp
   1.833  and
   1.834  .Pn repl
   1.835 @@ -4109,38 +4101,34 @@
   1.836  and
   1.837  .Pn whatnow
   1.838  and
   1.839 -.Pn viamail ,
   1.840 -they all (!) have the same message sending function included, as well.
   1.841 -In result,
   1.842 +.Pn viamail
   1.843 +\(en they all (!) \(en
   1.844 +have the same annotating and sending functions included, once more.
   1.845 +As a result,
   1.846  .Pn comp
   1.847  sends messages without using
   1.848  .Pn send .
   1.849  The situation is the same as if
   1.850  .Pn grep
   1.851 -would page without
   1.852 +would page its output without using
   1.853  .Pn more
   1.854  just because both programs are part of the same code base.
   1.855  .P
   1.856 -The clear separation on the surface \(en the tool chest approach \(en
   1.857 +The clear separation on the surface of nmh
   1.858 +\(en the tool chest approach \(en
   1.859  is violated on the level below.
   1.860  This violation is for the sake of time performance.
   1.861 -On systems where
   1.862 -.Fu fork()
   1.863 -and
   1.864 -.Fu exec()
   1.865 -are expensive, the quicker response might be noticable.
   1.866 -In the old times, sacrificing readability and conceptional beauty for
   1.867 -speed might even have been a must to prevent MH from being unusably slow.
   1.868 -Whatever the reasons had been, today they are gone.
   1.869 -No longer should we sacrifice readability or conceptional beauty.
   1.870 -No longer should we violate the Unix philosophy's ``one tool, one job''
   1.871 -guideline.
   1.872 -.\" XXX ref
   1.873 -No longer should we keep speed improvements that became unnecessary.
   1.874 -.P
   1.875 +Decades ago, sacrificing readability and conceptional beauty
   1.876 +for speed might have been necessary to prevent MH from being
   1.877 +unusably slow, but today this is not the case anymore.
   1.878 +No longer should speed improvements that became unnecessary be kept.
   1.879 +No longer should readability or conceptional beauty be sacrificed.
   1.880 +No longer should the Unix philosophy's ``one tool, one job''
   1.881 +guideline be violated.
   1.882  Therefore, mmh's
   1.883  .Pn comp
   1.884 -does no longer send messages.
   1.885 +no longer sends messages.
   1.886 +.P
   1.887  In mmh, different jobs are divided among separate programs that
   1.888  invoke each other as needed.
   1.889  In consequence,
   1.890 @@ -4148,55 +4136,40 @@
   1.891  invokes
   1.892  .Pn whatnow
   1.893  which thereafter invokes
   1.894 -.Pn send .
   1.895 +.Pn send
   1.896  .Ci 3df5ab3c116e6d4a2fb4bb5cc9dfc5f781825815
   1.897 -.Ci c73c00bfccd22ec77e9593f47462aeca4a8cd9c0
   1.898 +.Ci c73c00bfccd22ec77e9593f47462aeca4a8cd9c0 .
   1.899  The clear separation on the surface is maintained on the level below.
   1.900 -Human users and the tools use the same interface \(en
   1.901 +Human users and other tools use the same interface \(en
   1.902  annotations, for example, are made by invoking
   1.903  .Pn anno ,
   1.904 -no matter if requested by programs or by human beings.
   1.905 +no matter if requested by programs or by human beings
   1.906  .Ci 469a4163c2a1a43731d412eaa5d9cae7d670c48b
   1.907  .Ci aed384169af5204b8002d06e7a22f89197963d2d
   1.908 -.Ci 3caf9e298a8861729ca8b8a84f57022b6f3ea742
   1.909 +.Ci 3caf9e298a8861729ca8b8a84f57022b6f3ea742 .
   1.910  The decrease of tools built from multiple source files and thus
   1.911  the decrease of
   1.912  .Fn uip/*sbr.c
   1.913 -files confirm the improvement.
   1.914 +files confirm the improvement
   1.915  .Ci 9e6d91313f01c96b4058d6bf419a8ca9a207bc33
   1.916  .ci 81744a46ac9f845d6c2b9908074d269275178d2e
   1.917  .Ci f0f858069d21111f0dbea510044593f89c9b0829
   1.918  .Ci 0503a6e9be34f24858b55b555a5c948182b9f24b
   1.919  .Ci 27826f9353e0f0b04590b7d0f8f83e60462b90f0
   1.920  .Ci d1da1f94ce62160aebb30df4063ccbc53768656b
   1.921 -.Ci c42222869e318fff5dec395eca3e776db3075455
   1.922 -.P
   1.923 -.\" XXX move this paragraph up somewhere
   1.924 -One disadvantage needs to be taken with this change:
   1.925 -The compiler can no longer check the integrity of the interfaces.
   1.926 -By changing the command line interfaces of tools, it is
   1.927 -the developer's job to adjust the invocations of these tools as well.
   1.928 -As this is a manual task and regression tests, which could detect such
   1.929 -problems, are not available yet, it is prone to errors.
   1.930 -These errors will not be detected at compile time but at run time.
   1.931 -Installing regression tests is a pending task.
   1.932 -In the best case, a uniform way of invoking tools from other tools
   1.933 -can be developed to allow automated testing at compile time.
   1.934 +.Ci c42222869e318fff5dec395eca3e776db3075455 .
   1.935 +This is also visible in the complexity of the build dependency graphs:
   1.936  
   1.937 +.sp
   1.938 +Nmh:
   1.939 +.BP input/deps-nmh.eps .5i
   1.940 +.EP
   1.941 +.sp
   1.942 +Mmh:
   1.943 +.BP input/deps-mmh.eps .8i
   1.944 +.EP
   1.945  
   1.946 -.ig 
   1.947 -XXX consider writing about mhl vs. mhlproc
   1.948 -
   1.949 -sbr/showfile.c
   1.950 -
   1.951 -    23          /*
   1.952 -    24          ** If you have your lproc listed as "mhl",
   1.953 -    25          ** then really invoked the mhlproc instead
   1.954 -    26          ** (which is usually mhl anyway).
   1.955 -    27          */
   1.956 -
   1.957 -Sat Nov 24 19:09:14 1984  /mtr (agent: Marshall Rose) <uci@udel-dewey>
   1.958 -
   1.959 -        sbr/showfile.c: if lproc is "mhl", use mhlproc for consistency
   1.960 -        (Actually, user should use "lproc: show", "showproc: mhl".)
   1.961 -..
   1.962 +The figures display all program to source file relationships
   1.963 +that are not one-to-one,
   1.964 +i.e. all programs that are built from multiple source files.
   1.965 +The primary source file of each program is omited from the graph.