1.1 --- a/discussion.roff	Tue Jul 10 11:46:20 2012 +0200
     1.2 +++ b/discussion.roff	Tue Jul 10 13:08:51 2012 +0200
     1.3 @@ -1,8 +1,9 @@
     1.4  .H0 "Discussion
     1.5  .P
     1.6 -This main chapter discusses the practical work done in the mmh project.
     1.7 -It is structured along the goals to achieve.
     1.8 -The concrete work done
     1.9 +This main chapter discusses the practical work accomplished in the
    1.10 +mmh project.
    1.11 +It is structured along the goals set for the project.
    1.12 +The concrete work undertaken
    1.13  is described in the examples of how the general goals were achieved.
    1.14  The discussion compares the current version of mmh with the state of
    1.15  nmh just before the mmh project started, i.e. Fall 2011.
    1.16 @@ -15,15 +16,16 @@
    1.17  .H1 "Streamlining
    1.18  
    1.19  .P
    1.20 -MH had been considered an all-in-one system for mail handling.
    1.21 -The community around nmh has a similar understanding.
    1.22 -In fundamental difference, mmh shall be a MUA only.
    1.23 +MH once provided anything necessary for email handling.
    1.24 +The community around nmh has the similar understanding that nmh should
    1.25 +provide a complete email system.
    1.26 +In fundamental contrast, mmh shall be a MUA only.
    1.27  I believe that the development of all-in-one mail systems is obsolete.
    1.28  Today, email is too complex to be fully covered by single projects.
    1.29  Such a project won't be able to excel in all aspects.
    1.30  Instead, the aspects of email should be covered by multiple projects,
    1.31  which then can be combined to form a complete system.
    1.32 -Excellent implementations for the various aspects of email exist already.
    1.33 +Excellent implementations for the various aspects of email already exist.
    1.34  Just to name three examples: Postfix is a specialized MTA,
    1.35  .\" XXX homepages verlinken
    1.36  Procmail is a specialized MDA, and Fetchmail is a specialized MRA.
    1.37 @@ -31,24 +33,23 @@
    1.38  providing the same function again as a side-component in the project.
    1.39  .\" XXX mail agent picture here
    1.40  .P
    1.41 -Doing something well, requires to focus on a small set of specific aspects.
    1.42 -Under the assumption that focused development produces better results
    1.43 -in the particular area, specialized projects will be superior
    1.44 +Doing something well requires focusing on a small set of specific aspects.
    1.45 +Under the assumption that development focussed on a particular area
    1.46 +produces better results there, specialized projects will be superior
    1.47  in their field of focus.
    1.48  Hence, all-in-one mail system projects \(en no matter if monolithic
    1.49  or modular \(en will never be the best choice in any of the fields.
    1.50 -Even in providing the best consistent all-in-one system they are likely
    1.51 +Even in providing the best consistent all-in-one system, they are likely
    1.52  to be beaten by projects that focus only on integrating existing mail
    1.53 -components to a homogeneous system.
    1.54 +components to create a homogeneous system.
    1.55  .P
    1.56 -The limiting resource in Free Software community development
    1.57 +The limiting resource in the community development of Free Software
    1.58  is usually man power.
    1.59  If the development power is spread over a large development area,
    1.60  it becomes even more difficult to compete with the specialists in the
    1.61  various fields.
    1.62  The concrete situation for MH-based mail systems is even tougher,
    1.63 -given the small and aged community, including both developers and users,
    1.64 -it has.
    1.65 +given their small and aged community, concerning both developers and users.
    1.66  .P
    1.67  In consequence, I believe that the available development resources
    1.68  should focus on the point where MH is most unique.
    1.69 @@ -62,10 +63,10 @@
    1.70  In contrast to nmh, which also provides mail submission and mail retrieval
    1.71  agents, mmh is a MUA only.
    1.72  This general difference initiated the development of mmh.
    1.73 -Removing the mail transfer facilities had been the first work task
    1.74 +The removal of the mail transfer facilities was the first work task
    1.75  in the mmh project.
    1.76  .P
    1.77 -Focusing on one mail agent role only is motivated by Eric Allman's
    1.78 +Focusing on one mail agent role only, is motivated by Eric Allman's
    1.79  experience with Sendmail.
    1.80  He identified the limitation of Sendmail to the MTA task as one reason for
    1.81  its success:
    1.82 @@ -86,13 +87,13 @@
    1.83  .Pn post
    1.84  command, established network connections and spoke SMTP to submit
    1.85  messages to be relayed to the outside world.
    1.86 -The changes in email demanded changes in this part of nmh too.
    1.87 +The changes in email demanded changes in this part of nmh as well.
    1.88  Encryption and authentication for network connections
    1.89  needed to be supported, hence TLS and SASL were introduced into nmh.
    1.90  This added complexity to nmh without improving it in its core functions.
    1.91  Also, keeping up with recent developments in the field of
    1.92  mail transfer requires development power and specialists.
    1.93 -In mmh this whole facility was simply cut off.
    1.94 +In mmh, this whole facility was simply cut off.
    1.95  .Ci f6aa95b724fd8c791164abe7ee5468bf5c34f226
    1.96  .Ci fecd5d34f65597a4dfa16aeabea7d74b191532c3
    1.97  .Ci 156d35f6425bea4c1ed3c4c79783dc613379c65b
    1.98 @@ -111,24 +112,24 @@
    1.99  VE
   1.100  The requirement to parse the recipient addresses out of the message header 
   1.101  is likely to be removed in the future.
   1.102 -Then mmh would give the recipient addresses as command line arguments.
   1.103 +Then mmh would pass the recipient addresses as command line arguments.
   1.104  This appears to be the better interface.
   1.105  .\" XXX implement it
   1.106  .P
   1.107  To retrieve mail, the
   1.108  .Pn inc
   1.109 -command acted as Mail Retrieval Agent (MRA).
   1.110 +command acted as an Mail Retrieval Agent (MRA).
   1.111  It established network connections
   1.112  and spoke POP3 to retrieve mail from remote servers.
   1.113  As with mail submission, the network connections required encryption and
   1.114  authentication, thus TLS and SASL were added.
   1.115 -Support for message retrieval through IMAP will become necessary
   1.116 -to be added soon, too, and likewise for any other changes in mail transfer.
   1.117 +Support for message retrieval through IMAP will soon become necessary
   1.118 +additions, too, and likewise for any other changes in mail transfer.
   1.119  Not so for mmh because it has dropped the support for retrieving mail
   1.120  from remote locations.
   1.121  .Ci ab7b48411962d26439f92f35ed084d3d6275459c
   1.122  Instead, it depends on an external tool to cover this task.
   1.123 -In mmh, two paths exist for messages to enter mmh's mail storage:
   1.124 +Mmh has two paths for messages to enter mmh's mail storage:
   1.125  (1) Mail can be incorporated with
   1.126  .Pn inc
   1.127  from the system maildrop, or (2) with
   1.128 @@ -140,7 +141,7 @@
   1.129  Now, of course, mmh depends on third-party software.
   1.130  An external MSA is required to transfer mail to the outside world;
   1.131  an external MRA is required to retrieve mail from remote machines.
   1.132 -There exist excellent implementations of such software,
   1.133 +Excellent implementations of such software exist,
   1.134  which likely are superior than the internal version.
   1.135  Additionally, the best suiting programs can be freely chosen.
   1.136  .P
   1.137 @@ -167,11 +168,11 @@
   1.138  to the programs but to the project itself.
   1.139  In other words:
   1.140  Develop projects that focus on one thing and do it well.
   1.141 -Projects grown complex should be split for the same reasons programs
   1.142 -grown complex should be split.
   1.143 +Projects which have grown complex should be split, for the same
   1.144 +reasons that programs which have grown complex should be split.
   1.145  If it is conceptionally more elegant to have the MSA and MRA as
   1.146  separate projects then they should be separated.
   1.147 -This is the case here, in my opinion.
   1.148 +In my opinion, this is the case here.
   1.149  The RFCs propose this separation by clearly distinguishing the different
   1.150  mail handling tasks.
   1.151  .[
   1.152 @@ -179,11 +180,10 @@
   1.153  .]
   1.154  The small interfaces between the mail agents support the separation.
   1.155  .P
   1.156 -In the beginning, email had been small and simple.
   1.157 +Email once had been small and simple.
   1.158  At that time,
   1.159  .Pn /bin/mail
   1.160 -had covered anything there was to email and still had been small
   1.161 -and simple.
   1.162 +had covered everything there was to email and still was small and simple.
   1.163  Later, the essential complexity of email increased.
   1.164  (Essential complexity is the complexity defined by the problem itself.\0
   1.165  .[[
   1.166 @@ -193,42 +193,44 @@
   1.167  RFCs started to introduce the concept of mail agents to separate the
   1.168  various tasks because they became more extensive and new tasks appeared.
   1.169  As the mail systems grew even more, parts were split off.
   1.170 -In nmh, for instance, the POP server, which was included in the original
   1.171 -MH, was removed.
   1.172 +For instance, a POP server was included in the original MH;
   1.173 +it was removed in nmh.
   1.174  Now is the time to go one step further and split off the MSA and MRA, too.
   1.175  Not only does this decrease the code size of the project,
   1.176 -but, more important, it unburdens mmh of the whole field of
   1.177 +more importantly, it unburdens mmh of the whole field of
   1.178  message transfer with all its implications for the project.
   1.179 -There is no more need to concern with changes in network transfer.
   1.180 -This independence is received by depending on an external program
   1.181 +There is no more need for concern with changes in network transfer.
   1.182 +This independence is gained by depending on an external program
   1.183  that covers the field.
   1.184  Today, this is a reasonable exchange.
   1.185  .P
   1.186  .\" XXX ueberleitung ???
   1.187  Functionality can be added in three different ways:
   1.188  .BU
   1.189 -Implementing the function originally in the project.
   1.190 +Implementing the function in the project itself.
   1.191  .BU
   1.192  Depending on a library that provides the function.
   1.193  .BU
   1.194  Depending on a program that provides the function.
   1.195  .P
   1.196  .\" XXX Rework sentence
   1.197 -While adding the function originally to the project increases the
   1.198 -code size most and requires most maintenance and development work,
   1.199 -it makes the project most independent of other software.
   1.200 -Using libraries or external programs require less maintenance work
   1.201 +While implementing the function in the project itself leads to the
   1.202 +largest increase in code size and requires the most maintenance
   1.203 +and development work,
   1.204 +it increases the project's independence of other software the most.
   1.205 +Using libraries or external programs requires less maintenance work
   1.206  but introduces dependencies on external software.
   1.207 -Programs have the smallest interfaces and provide the best separation
   1.208 +Programs have the smallest interfaces and provide the best separation,
   1.209  but possibly limit the information exchange.
   1.210 -External libraries are stronger connected than external programs,
   1.211 -thus information can be exchanged more flexible.
   1.212 +External libraries are more strongly connected than external programs,
   1.213 +thus information can be exchanged in a more flexible manner.
   1.214  Adding code to a project increases maintenance work.
   1.215  .\" XXX ref
   1.216  Implementing complex functions in the project itself adds
   1.217  a lot of code.
   1.218  This should be avoided if possible.
   1.219 -Hence, the dependencies only change in kind, not in their existence.
   1.220 +Hence, the dependencies only change in their character,
   1.221 +not in their existence.
   1.222  In mmh, library dependencies on
   1.223  .Pn libsasl2
   1.224  and
   1.225 @@ -237,8 +239,8 @@
   1.226  were traded against program dependencies on an MSA and an MRA.
   1.227  This also meant trading build-time dependencies against run-time
   1.228  dependencies.
   1.229 -Besides program dependencies providing the stronger separation
   1.230 -and being more flexible, they also allowed
   1.231 +Besides providing stronger separation and greater flexibility,
   1.232 +program dependencies also allowed
   1.233  over 6\|000 lines of code to be removed from mmh.
   1.234  This made mmh's code base about 12\|% smaller.
   1.235  Reducing the project's code size by such an amount without actually
   1.236 @@ -246,17 +248,17 @@
   1.237  Actually, as external MSAs and MRAs are likely superior to the
   1.238  project's internal versions, the common user even gains functionality.
   1.239  .P
   1.240 -Users of MH should not have problems to set up an external MSA and MRA.
   1.241 +Users of MH should not have problems setting up an external MSA and MRA.
   1.242  Also, the popular MSAs and MRAs have large communities and a lot
   1.243 -of documentation available.
   1.244 -Choices for MSAs range from full-featured MTAs like
   1.245 +of available documentation.
   1.246 +Choices for MSAs range from full-featured MTAs such as
   1.247  .\" XXX refs
   1.248 -.I Postfix
   1.249 -over mid-size MTAs like
   1.250 +.I Postfix ,
   1.251 +over mid-size MTAs such as
   1.252  .I masqmail
   1.253  and
   1.254 -.I dma
   1.255 -to small forwarders like
   1.256 +.I dma ,
   1.257 +to small forwarders such as
   1.258  .I ssmtp
   1.259  and
   1.260  .I nullmailer .
   1.261 @@ -271,13 +273,13 @@
   1.262  .H2 "Non-MUA Tools
   1.263  .P
   1.264  One goal of mmh is to remove the tools that are not part of the MUA's task.
   1.265 -Further more, any tools that don't improve the MUA's job significantly
   1.266 +Further more, any tools that don't significantly improve the MUA's job
   1.267  should be removed.
   1.268  Loosely related and rarely used tools distract from the lean appearance.
   1.269  They require maintenance work without adding much to the core task.
   1.270  By removing these tools, the project shall become more streamlined
   1.271  and focused.
   1.272 -In mmh the following tools are not available anymore:
   1.273 +In mmh, the following tools are not available anymore:
   1.274  .BU
   1.275  .Pn conflict
   1.276  was removed
   1.277 @@ -301,8 +303,8 @@
   1.278  If users like to be informed of new mail, the shell's
   1.279  .Ev MAILPATH
   1.280  variable or graphical notifications are technically more appealing.
   1.281 -Writing directly to terminals is hardly ever wanted today.
   1.282 -If though one wants to have it this way, the standard tool
   1.283 +Writing directly to terminals is hardly ever desired today.
   1.284 +If, though, one prefers this approach, the standard tool
   1.285  .Pn write
   1.286  can be used in a way similar to:
   1.287  .VS
   1.288 @@ -334,7 +336,7 @@
   1.289  ls -l /var/mail/meillo
   1.290  VE
   1.291  It did distinguish between old and new mail, but
   1.292 -this detail information can be retrieved with
   1.293 +these details can be retrieved with
   1.294  .Pn stat (1),
   1.295  too.
   1.296  A small shell script could be written to print the information
   1.297 @@ -343,7 +345,7 @@
   1.298  .Pn inc
   1.299  only incorporates mail from the user's local maildrop,
   1.300  and thus no data transfers over slow networks are involved,
   1.301 -there's hardly any need to check for new mail before incorporating it.
   1.302 +there is hardly any need to check for new mail before incorporating it.
   1.303  .BU
   1.304  .Pn msh
   1.305  was removed
   1.306 @@ -351,18 +353,18 @@
   1.307  because the tool was in conflict with the philosophy of MH.
   1.308  It provided an interactive shell to access the features of MH,
   1.309  but it wasn't just a shell tailored to the needs of mail handling.
   1.310 -Instead it was one large program that had several MH tools built in.
   1.311 +Instead, it was one large program that had several MH tools built in.
   1.312  This conflicts with the major feature of MH of being a tool chest.
   1.313  .Pn msh 's
   1.314  main use case had been accessing Bulletin Boards, which have ceased to
   1.315  be popular.
   1.316  .P
   1.317  Removing
   1.318 -.Pn msh ,
   1.319 +.Pn msh
   1.320  together with the truly archaic code relicts
   1.321  .Pn vmh
   1.322  and
   1.323 -.Pn wmh ,
   1.324 +.Pn wmh
   1.325  saved more than 7\|000 lines of C code \(en
   1.326  about 15\|% of the project's original source code amount.
   1.327  Having less code \(en with equal readability, of course \(en
   1.328 @@ -383,9 +385,9 @@
   1.329  is not related to the mail client, and
   1.330  .Pn msh
   1.331  conflicts with the basic concept of MH.
   1.332 -Theses two tools might still be useful, but they should not be part of mmh.
   1.333 +These two tools might still be useful, but they should not be part of mmh.
   1.334  .P
   1.335 -Finally, there's
   1.336 +Finally, there is
   1.337  .Pn slocal .
   1.338  .Pn slocal
   1.339  is an MDA and thus not directly MUA-related.
   1.340 @@ -399,11 +401,10 @@
   1.341  different folders, which is otherwise not available in mmh.
   1.342  Although
   1.343  .Pn slocal
   1.344 -does neither pull in dependencies nor does it include a separate
   1.345 +neither pulls in dependencies, nor does it include a separate
   1.346  technical area (cf. Sec.
   1.347  .Cf mail-transfer-facilities ),
   1.348 -still,
   1.349 -it accounts for about 1\|000 lines of code that need to be maintained.
   1.350 +it still accounts for about 1\|000 lines of code that need to be maintained.
   1.351  As
   1.352  .Pn slocal
   1.353  is almost self-standing, it should be split off into a separate project.
   1.354 @@ -427,7 +428,7 @@
   1.355  is not split off.
   1.356  I defer the decision over
   1.357  .Pn slocal
   1.358 -in need for deeper investigation.
   1.359 +out of a need for deeper investigation.
   1.360  In the meanwhile, it remains part of mmh.
   1.361  However, its continued existence is not significant because
   1.362  .Pn slocal
   1.363 @@ -865,7 +866,7 @@
   1.364  Removing the option removed a second code setup that would have
   1.365  needed to be tested.
   1.366  .\" XXX datum?
   1.367 -This change was first done in nmh and thereafter merged into mmh.
   1.368 +This change was first accomplished in nmh and thereafter merged into mmh.
   1.369  .P
   1.370  The interface changes in mmh require mh-e to be adjusted in order
   1.371  to be able to use mmh as back-end.
   1.372 @@ -2108,7 +2109,7 @@
   1.373  
   1.374  .U3 "Storing Attachments
   1.375  .P
   1.376 -Extracting MIME parts of a message and storing them to disk is done by
   1.377 +Extracting MIME parts of a message and storing them to disk is performed by
   1.378  .Pn mhstore .
   1.379  The program has two operation modes,
   1.380  .Sw -auto
   1.381 @@ -2279,7 +2280,7 @@
   1.382  profile entries can be used to display MIME parts in a specific way.
   1.383  For instance, PDF and Postscript files could be converted to plain text
   1.384  to display them in the terminal.
   1.385 -In mmh, the displaying of MIME parts will always be done serially.
   1.386 +In mmh, MIME parts will always be displayed serially.
   1.387  The request to display the MIME type `multipart/parallel' in parallel
   1.388  is ignored.
   1.389  It is simply treated as `multipart/mixed'.
   1.390 @@ -2311,8 +2312,8 @@
   1.391  Therefore,
   1.392  .Pe mhshow-charset-*
   1.393  profile entries used to be needed.
   1.394 -In mmh, the conversion is done automatically by piping the text through
   1.395 -the
   1.396 +In mmh, the conversion is performed automatically by piping the
   1.397 +text through the
   1.398  .Pn iconv
   1.399  command, if necessary.
   1.400  .Ci 2433122c20baccb10b70b49c04c6b0497b5b3b60
   1.401 @@ -2569,7 +2570,7 @@
   1.402  but applies them.
   1.403  .Cl "scan +drafts" ,
   1.404  for instance, is a truly natural request.
   1.405 -Most of the work was already done by Rose in the eighties.
   1.406 +Most of the work was already performed by Rose in the eighties.
   1.407  The original improvement of mmh is dropping the old draft message approach
   1.408  and thus simplifying the tools, the documentation and the system as a whole.
   1.409  Although my part in the draft handling improvement was small,
   1.410 @@ -2657,8 +2658,8 @@
   1.411  But most important is the ability to keep removed messages in the MH domain.
   1.412  Messages in the trash folder can be listed like those in any other folder.
   1.413  Deleted messages can be displayed like any other messages.
   1.414 -Restoring a deleted messages can be done with
   1.415 -.Pn refile .
   1.416 +.Pn refile
   1.417 +can restore deleted messages.
   1.418  All operations on deleted files are still covered by the MH tools.
   1.419  The trash folder is just like any other folder in the mail storage.
   1.420  .P
   1.421 @@ -2981,8 +2982,7 @@
   1.422  of related code parts.
   1.423  Having the new variables with descriptive names, a more
   1.424  straight forward implementation became apparent.
   1.425 -Before the clarification was done,
   1.426 -the possibility to improve had not be seen.
   1.427 +Before the code was clarified, the possibility to improve had not be seen.
   1.428  .Ci aa60b0ab5e804f8befa890c0a6df0e3143ce0723
   1.429  
   1.430  
   1.431 @@ -3529,9 +3529,8 @@
   1.432  and
   1.433  .Pn spost
   1.434  can be considered to be merged.
   1.435 -Direct invocations of
   1.436  .Pn spost
   1.437 -are only done by the to-be-changed
   1.438 +is only invoked directly by the to-be-changed
   1.439  .Pn mhmail
   1.440  implementation and by
   1.441  .Pn rcvdist ,
   1.442 @@ -3895,7 +3894,7 @@
   1.443  a MH-MIME library, as a companion to the MH standard library.
   1.444  This is left open for the future.
   1.445  .P
   1.446 -The work already done focussed on the non-MIME tools.
   1.447 +The work already accomplished focussed on the non-MIME tools.
   1.448  The amount of code compiled into each program was reduced.
   1.449  This eases the understanding of the code base.
   1.450  In nmh,

     2.1 --- a/intro.roff	Tue Jul 10 11:46:20 2012 +0200
     2.2 +++ b/intro.roff	Tue Jul 10 13:08:51 2012 +0200
     2.3 @@ -339,9 +339,8 @@
     2.4  They are familiar with the command line and enjoy its power.
     2.5  They are at least capable of shell scripting and want to improve their
     2.6  productivity by scripting the mail system.
     2.7 -.\" XXX Naturally, he uses ...
     2.8 -They naturally use modern email features, such as attachments,
     2.9 -non-ASCII text, digital signatures and message encryption.
    2.10 +They use modern email features, such as attachments,
    2.11 +non-ASCII text, digital signatures and message encryption in a natural way.
    2.12  They are able to setup email system components besides mmh,
    2.13  and actually like to have the choice to pick the ones they prefer.
    2.14  They have a reasonably modern operating system that complies to the