# HG changeset patch
# User markus schnalke <meillo@marmaro.de>
# Date 1341918531 -7200
# Node ID f4ffe121a0a259298e2e42f10b11c35afb61eb7f
# Parent  277eeb5ba22306cc4f737b5e2c1f8be4c00bce5f
Applied excellent suggestions and corrections by Kate.

diff -r 277eeb5ba223 -r f4ffe121a0a2 discussion.roff
--- a/discussion.roff	Tue Jul 10 11:46:20 2012 +0200
+++ b/discussion.roff	Tue Jul 10 13:08:51 2012 +0200
@@ -1,8 +1,9 @@
 .H0 "Discussion
 .P
-This main chapter discusses the practical work done in the mmh project.
-It is structured along the goals to achieve.
-The concrete work done
+This main chapter discusses the practical work accomplished in the
+mmh project.
+It is structured along the goals set for the project.
+The concrete work undertaken
 is described in the examples of how the general goals were achieved.
 The discussion compares the current version of mmh with the state of
 nmh just before the mmh project started, i.e. Fall 2011.
@@ -15,15 +16,16 @@
 .H1 "Streamlining
 
 .P
-MH had been considered an all-in-one system for mail handling.
-The community around nmh has a similar understanding.
-In fundamental difference, mmh shall be a MUA only.
+MH once provided anything necessary for email handling.
+The community around nmh has the similar understanding that nmh should
+provide a complete email system.
+In fundamental contrast, mmh shall be a MUA only.
 I believe that the development of all-in-one mail systems is obsolete.
 Today, email is too complex to be fully covered by single projects.
 Such a project won't be able to excel in all aspects.
 Instead, the aspects of email should be covered by multiple projects,
 which then can be combined to form a complete system.
-Excellent implementations for the various aspects of email exist already.
+Excellent implementations for the various aspects of email already exist.
 Just to name three examples: Postfix is a specialized MTA,
 .\" XXX homepages verlinken
 Procmail is a specialized MDA, and Fetchmail is a specialized MRA.
@@ -31,24 +33,23 @@
 providing the same function again as a side-component in the project.
 .\" XXX mail agent picture here
 .P
-Doing something well, requires to focus on a small set of specific aspects.
-Under the assumption that focused development produces better results
-in the particular area, specialized projects will be superior
+Doing something well requires focusing on a small set of specific aspects.
+Under the assumption that development focussed on a particular area
+produces better results there, specialized projects will be superior
 in their field of focus.
 Hence, all-in-one mail system projects \(en no matter if monolithic
 or modular \(en will never be the best choice in any of the fields.
-Even in providing the best consistent all-in-one system they are likely
+Even in providing the best consistent all-in-one system, they are likely
 to be beaten by projects that focus only on integrating existing mail
-components to a homogeneous system.
+components to create a homogeneous system.
 .P
-The limiting resource in Free Software community development
+The limiting resource in the community development of Free Software
 is usually man power.
 If the development power is spread over a large development area,
 it becomes even more difficult to compete with the specialists in the
 various fields.
 The concrete situation for MH-based mail systems is even tougher,
-given the small and aged community, including both developers and users,
-it has.
+given their small and aged community, concerning both developers and users.
 .P
 In consequence, I believe that the available development resources
 should focus on the point where MH is most unique.
@@ -62,10 +63,10 @@
 In contrast to nmh, which also provides mail submission and mail retrieval
 agents, mmh is a MUA only.
 This general difference initiated the development of mmh.
-Removing the mail transfer facilities had been the first work task
+The removal of the mail transfer facilities was the first work task
 in the mmh project.
 .P
-Focusing on one mail agent role only is motivated by Eric Allman's
+Focusing on one mail agent role only, is motivated by Eric Allman's
 experience with Sendmail.
 He identified the limitation of Sendmail to the MTA task as one reason for
 its success:
@@ -86,13 +87,13 @@
 .Pn post
 command, established network connections and spoke SMTP to submit
 messages to be relayed to the outside world.
-The changes in email demanded changes in this part of nmh too.
+The changes in email demanded changes in this part of nmh as well.
 Encryption and authentication for network connections
 needed to be supported, hence TLS and SASL were introduced into nmh.
 This added complexity to nmh without improving it in its core functions.
 Also, keeping up with recent developments in the field of
 mail transfer requires development power and specialists.
-In mmh this whole facility was simply cut off.
+In mmh, this whole facility was simply cut off.
 .Ci f6aa95b724fd8c791164abe7ee5468bf5c34f226
 .Ci fecd5d34f65597a4dfa16aeabea7d74b191532c3
 .Ci 156d35f6425bea4c1ed3c4c79783dc613379c65b
@@ -111,24 +112,24 @@
 VE
 The requirement to parse the recipient addresses out of the message header 
 is likely to be removed in the future.
-Then mmh would give the recipient addresses as command line arguments.
+Then mmh would pass the recipient addresses as command line arguments.
 This appears to be the better interface.
 .\" XXX implement it
 .P
 To retrieve mail, the
 .Pn inc
-command acted as Mail Retrieval Agent (MRA).
+command acted as an Mail Retrieval Agent (MRA).
 It established network connections
 and spoke POP3 to retrieve mail from remote servers.
 As with mail submission, the network connections required encryption and
 authentication, thus TLS and SASL were added.
-Support for message retrieval through IMAP will become necessary
-to be added soon, too, and likewise for any other changes in mail transfer.
+Support for message retrieval through IMAP will soon become necessary
+additions, too, and likewise for any other changes in mail transfer.
 Not so for mmh because it has dropped the support for retrieving mail
 from remote locations.
 .Ci ab7b48411962d26439f92f35ed084d3d6275459c
 Instead, it depends on an external tool to cover this task.
-In mmh, two paths exist for messages to enter mmh's mail storage:
+Mmh has two paths for messages to enter mmh's mail storage:
 (1) Mail can be incorporated with
 .Pn inc
 from the system maildrop, or (2) with
@@ -140,7 +141,7 @@
 Now, of course, mmh depends on third-party software.
 An external MSA is required to transfer mail to the outside world;
 an external MRA is required to retrieve mail from remote machines.
-There exist excellent implementations of such software,
+Excellent implementations of such software exist,
 which likely are superior than the internal version.
 Additionally, the best suiting programs can be freely chosen.
 .P
@@ -167,11 +168,11 @@
 to the programs but to the project itself.
 In other words:
 Develop projects that focus on one thing and do it well.
-Projects grown complex should be split for the same reasons programs
-grown complex should be split.
+Projects which have grown complex should be split, for the same
+reasons that programs which have grown complex should be split.
 If it is conceptionally more elegant to have the MSA and MRA as
 separate projects then they should be separated.
-This is the case here, in my opinion.
+In my opinion, this is the case here.
 The RFCs propose this separation by clearly distinguishing the different
 mail handling tasks.
 .[
@@ -179,11 +180,10 @@
 .]
 The small interfaces between the mail agents support the separation.
 .P
-In the beginning, email had been small and simple.
+Email once had been small and simple.
 At that time,
 .Pn /bin/mail
-had covered anything there was to email and still had been small
-and simple.
+had covered everything there was to email and still was small and simple.
 Later, the essential complexity of email increased.
 (Essential complexity is the complexity defined by the problem itself.\0
 .[[
@@ -193,42 +193,44 @@
 RFCs started to introduce the concept of mail agents to separate the
 various tasks because they became more extensive and new tasks appeared.
 As the mail systems grew even more, parts were split off.
-In nmh, for instance, the POP server, which was included in the original
-MH, was removed.
+For instance, a POP server was included in the original MH;
+it was removed in nmh.
 Now is the time to go one step further and split off the MSA and MRA, too.
 Not only does this decrease the code size of the project,
-but, more important, it unburdens mmh of the whole field of
+more importantly, it unburdens mmh of the whole field of
 message transfer with all its implications for the project.
-There is no more need to concern with changes in network transfer.
-This independence is received by depending on an external program
+There is no more need for concern with changes in network transfer.
+This independence is gained by depending on an external program
 that covers the field.
 Today, this is a reasonable exchange.
 .P
 .\" XXX ueberleitung ???
 Functionality can be added in three different ways:
 .BU
-Implementing the function originally in the project.
+Implementing the function in the project itself.
 .BU
 Depending on a library that provides the function.
 .BU
 Depending on a program that provides the function.
 .P
 .\" XXX Rework sentence
-While adding the function originally to the project increases the
-code size most and requires most maintenance and development work,
-it makes the project most independent of other software.
-Using libraries or external programs require less maintenance work
+While implementing the function in the project itself leads to the
+largest increase in code size and requires the most maintenance
+and development work,
+it increases the project's independence of other software the most.
+Using libraries or external programs requires less maintenance work
 but introduces dependencies on external software.
-Programs have the smallest interfaces and provide the best separation
+Programs have the smallest interfaces and provide the best separation,
 but possibly limit the information exchange.
-External libraries are stronger connected than external programs,
-thus information can be exchanged more flexible.
+External libraries are more strongly connected than external programs,
+thus information can be exchanged in a more flexible manner.
 Adding code to a project increases maintenance work.
 .\" XXX ref
 Implementing complex functions in the project itself adds
 a lot of code.
 This should be avoided if possible.
-Hence, the dependencies only change in kind, not in their existence.
+Hence, the dependencies only change in their character,
+not in their existence.
 In mmh, library dependencies on
 .Pn libsasl2
 and
@@ -237,8 +239,8 @@
 were traded against program dependencies on an MSA and an MRA.
 This also meant trading build-time dependencies against run-time
 dependencies.
-Besides program dependencies providing the stronger separation
-and being more flexible, they also allowed
+Besides providing stronger separation and greater flexibility,
+program dependencies also allowed
 over 6\|000 lines of code to be removed from mmh.
 This made mmh's code base about 12\|% smaller.
 Reducing the project's code size by such an amount without actually
@@ -246,17 +248,17 @@
 Actually, as external MSAs and MRAs are likely superior to the
 project's internal versions, the common user even gains functionality.
 .P
-Users of MH should not have problems to set up an external MSA and MRA.
+Users of MH should not have problems setting up an external MSA and MRA.
 Also, the popular MSAs and MRAs have large communities and a lot
-of documentation available.
-Choices for MSAs range from full-featured MTAs like
+of available documentation.
+Choices for MSAs range from full-featured MTAs such as
 .\" XXX refs
-.I Postfix
-over mid-size MTAs like
+.I Postfix ,
+over mid-size MTAs such as
 .I masqmail
 and
-.I dma
-to small forwarders like
+.I dma ,
+to small forwarders such as
 .I ssmtp
 and
 .I nullmailer .
@@ -271,13 +273,13 @@
 .H2 "Non-MUA Tools
 .P
 One goal of mmh is to remove the tools that are not part of the MUA's task.
-Further more, any tools that don't improve the MUA's job significantly
+Further more, any tools that don't significantly improve the MUA's job
 should be removed.
 Loosely related and rarely used tools distract from the lean appearance.
 They require maintenance work without adding much to the core task.
 By removing these tools, the project shall become more streamlined
 and focused.
-In mmh the following tools are not available anymore:
+In mmh, the following tools are not available anymore:
 .BU
 .Pn conflict
 was removed
@@ -301,8 +303,8 @@
 If users like to be informed of new mail, the shell's
 .Ev MAILPATH
 variable or graphical notifications are technically more appealing.
-Writing directly to terminals is hardly ever wanted today.
-If though one wants to have it this way, the standard tool
+Writing directly to terminals is hardly ever desired today.
+If, though, one prefers this approach, the standard tool
 .Pn write
 can be used in a way similar to:
 .VS
@@ -334,7 +336,7 @@
 ls -l /var/mail/meillo
 VE
 It did distinguish between old and new mail, but
-this detail information can be retrieved with
+these details can be retrieved with
 .Pn stat (1),
 too.
 A small shell script could be written to print the information
@@ -343,7 +345,7 @@
 .Pn inc
 only incorporates mail from the user's local maildrop,
 and thus no data transfers over slow networks are involved,
-there's hardly any need to check for new mail before incorporating it.
+there is hardly any need to check for new mail before incorporating it.
 .BU
 .Pn msh
 was removed
@@ -351,18 +353,18 @@
 because the tool was in conflict with the philosophy of MH.
 It provided an interactive shell to access the features of MH,
 but it wasn't just a shell tailored to the needs of mail handling.
-Instead it was one large program that had several MH tools built in.
+Instead, it was one large program that had several MH tools built in.
 This conflicts with the major feature of MH of being a tool chest.
 .Pn msh 's
 main use case had been accessing Bulletin Boards, which have ceased to
 be popular.
 .P
 Removing
-.Pn msh ,
+.Pn msh
 together with the truly archaic code relicts
 .Pn vmh
 and
-.Pn wmh ,
+.Pn wmh
 saved more than 7\|000 lines of C code \(en
 about 15\|% of the project's original source code amount.
 Having less code \(en with equal readability, of course \(en
@@ -383,9 +385,9 @@
 is not related to the mail client, and
 .Pn msh
 conflicts with the basic concept of MH.
-Theses two tools might still be useful, but they should not be part of mmh.
+These two tools might still be useful, but they should not be part of mmh.
 .P
-Finally, there's
+Finally, there is
 .Pn slocal .
 .Pn slocal
 is an MDA and thus not directly MUA-related.
@@ -399,11 +401,10 @@
 different folders, which is otherwise not available in mmh.
 Although
 .Pn slocal
-does neither pull in dependencies nor does it include a separate
+neither pulls in dependencies, nor does it include a separate
 technical area (cf. Sec.
 .Cf mail-transfer-facilities ),
-still,
-it accounts for about 1\|000 lines of code that need to be maintained.
+it still accounts for about 1\|000 lines of code that need to be maintained.
 As
 .Pn slocal
 is almost self-standing, it should be split off into a separate project.
@@ -427,7 +428,7 @@
 is not split off.
 I defer the decision over
 .Pn slocal
-in need for deeper investigation.
+out of a need for deeper investigation.
 In the meanwhile, it remains part of mmh.
 However, its continued existence is not significant because
 .Pn slocal
@@ -865,7 +866,7 @@
 Removing the option removed a second code setup that would have
 needed to be tested.
 .\" XXX datum?
-This change was first done in nmh and thereafter merged into mmh.
+This change was first accomplished in nmh and thereafter merged into mmh.
 .P
 The interface changes in mmh require mh-e to be adjusted in order
 to be able to use mmh as back-end.
@@ -2108,7 +2109,7 @@
 
 .U3 "Storing Attachments
 .P
-Extracting MIME parts of a message and storing them to disk is done by
+Extracting MIME parts of a message and storing them to disk is performed by
 .Pn mhstore .
 The program has two operation modes,
 .Sw -auto
@@ -2279,7 +2280,7 @@
 profile entries can be used to display MIME parts in a specific way.
 For instance, PDF and Postscript files could be converted to plain text
 to display them in the terminal.
-In mmh, the displaying of MIME parts will always be done serially.
+In mmh, MIME parts will always be displayed serially.
 The request to display the MIME type `multipart/parallel' in parallel
 is ignored.
 It is simply treated as `multipart/mixed'.
@@ -2311,8 +2312,8 @@
 Therefore,
 .Pe mhshow-charset-*
 profile entries used to be needed.
-In mmh, the conversion is done automatically by piping the text through
-the
+In mmh, the conversion is performed automatically by piping the
+text through the
 .Pn iconv
 command, if necessary.
 .Ci 2433122c20baccb10b70b49c04c6b0497b5b3b60
@@ -2569,7 +2570,7 @@
 but applies them.
 .Cl "scan +drafts" ,
 for instance, is a truly natural request.
-Most of the work was already done by Rose in the eighties.
+Most of the work was already performed by Rose in the eighties.
 The original improvement of mmh is dropping the old draft message approach
 and thus simplifying the tools, the documentation and the system as a whole.
 Although my part in the draft handling improvement was small,
@@ -2657,8 +2658,8 @@
 But most important is the ability to keep removed messages in the MH domain.
 Messages in the trash folder can be listed like those in any other folder.
 Deleted messages can be displayed like any other messages.
-Restoring a deleted messages can be done with
-.Pn refile .
+.Pn refile
+can restore deleted messages.
 All operations on deleted files are still covered by the MH tools.
 The trash folder is just like any other folder in the mail storage.
 .P
@@ -2981,8 +2982,7 @@
 of related code parts.
 Having the new variables with descriptive names, a more
 straight forward implementation became apparent.
-Before the clarification was done,
-the possibility to improve had not be seen.
+Before the code was clarified, the possibility to improve had not be seen.
 .Ci aa60b0ab5e804f8befa890c0a6df0e3143ce0723
 
 
@@ -3529,9 +3529,8 @@
 and
 .Pn spost
 can be considered to be merged.
-Direct invocations of
 .Pn spost
-are only done by the to-be-changed
+is only invoked directly by the to-be-changed
 .Pn mhmail
 implementation and by
 .Pn rcvdist ,
@@ -3895,7 +3894,7 @@
 a MH-MIME library, as a companion to the MH standard library.
 This is left open for the future.
 .P
-The work already done focussed on the non-MIME tools.
+The work already accomplished focussed on the non-MIME tools.
 The amount of code compiled into each program was reduced.
 This eases the understanding of the code base.
 In nmh,
diff -r 277eeb5ba223 -r f4ffe121a0a2 intro.roff
--- a/intro.roff	Tue Jul 10 11:46:20 2012 +0200
+++ b/intro.roff	Tue Jul 10 13:08:51 2012 +0200
@@ -339,9 +339,8 @@
 They are familiar with the command line and enjoy its power.
 They are at least capable of shell scripting and want to improve their
 productivity by scripting the mail system.
-.\" XXX Naturally, he uses ...
-They naturally use modern email features, such as attachments,
-non-ASCII text, digital signatures and message encryption.
+They use modern email features, such as attachments,
+non-ASCII text, digital signatures and message encryption in a natural way.
 They are able to setup email system components besides mmh,
 and actually like to have the choice to pick the ones they prefer.
 They have a reasonably modern operating system that complies to the