docs/master: ch03.roff comparison

comparison ch03.roff @ 100:6ae7dc4a3a02

Included changes proposed by Lydi.

author	markus schnalke <meillo@marmaro.de>
date	Tue, 19 Jun 2012 10:54:50 +0200
parents	d894191d7a33
children	e8e6adb14beb

comparison

equal deleted inserted replaced

-:468c2bdc6b1a
+:6ae7dc4a3a02
 Current changes of nmh will be mentioned only as side notes.
 .\" XXX where do I discuss the parallel development of nmh?
-.H1 "Stream-lining
+.H1 "Stream-Lining
 .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.
 I believe that it is best to use such specialized tools instead of
 providing the same function again as a side-component in the project.
 .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 likely be superior
+in the particular area, 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
 to be beaten by projects that focus only on integrating existing mail
 The concrete situation for MH-based mail systems is even tougher,
 given the small and aged community, including both developers and users,
 it has.
 .P
 In consequence, I believe that the available development resources
-should be focused on the point where MH is most unique.
+should focus on the point where MH is most unique.
 This is clearly the user interface \(en the MUA.
 Peripheral parts should be removed to stream-line mmh for the MUA task.
-.H2 "Removal of the Mail Transfer Facilities
+.H2 "Mail Transfer Facilities
 .P
 In contrast to nmh, which also provides mail submission and mail retrieval
 agents, mmh is a MUA only.
-This general difference in the view on the character of nmh
+This general difference initiated the development of mmh.
-initiated the development of mmh.
 Removing the mail transfer facilities had been the first work task
 in the mmh project.
 .P
-The MSA is called \fIMessage Transfer Service\fP (MTS) in nmh.
+The Mail Submission Agent (MSA) is called
+\fIMessage Transfer Service\fP (MTS) in nmh.
 The facility established network connections and spoke SMTP to submit
 messages for relay to the outside world.
 This part was implemented by the
 .Pn post
 command.
 exec qmail-inject
 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.
-This is clearly the better interface, but mmh does not provide it yet.
+This appears to be the better interface.
 .\" XXX implement it
 .P
 To retrieve mail, the
 .Pn inc
-command established network connections
+command acted as 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 so on for any changes in mail transfer.
+to be added soon, too, and likewise for any other changes in mail transfer.
-Mmh has dropped the support for retrieving mail from remote locations.
+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 there exist two paths for messages to enter mmh's mail storage:
+In mmh exist two paths for messages to enter mmh's mail storage:
-(1) Mail can be incorporate with
+(1) Mail can be incorporated with
 .Pn inc
 from the system maildrop, or (2) with
 .Pn rcvstore
 by reading them, one at a time, from the standard input.
 .P
 With the removal of the MSA and MRA, mmh converted from an all-in-one
 mail system to being a MUA only.
-Following the Unix philosophy, it now focuses on one job and
-tries to do that one well.
-Not only the programs follow that tenet but also the project itself does so.
 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,
 which do this specific task likely better than the internal
 the command line tools, for the cases when
 .Pn more
 or
 .Pn less
 aren't available, appears to be ridiculous.
-Now, an MSA or MRA is more complex than a text pager
+Of course, MSAs and MRAs are more complex than text pagers
 and not necessarily available but still the concept of orthogonal
 design holds: ``Write programs that do one thing and do it well.''
 .[
 mcilroy unix phil
 p. 53
 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.
-If it is conceptionally more elegant to have the MSA and MRA
+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.
 The RFCs propose this separation by clearly distinguishing the different
 mail handling tasks.
 .[
 rfc 821
 .]
 The small interfaces between the mail agents support the separation.
 .P
 In the beginning, email had been small and simple.
-(\c
+At that time,
 .Pn /bin/mail
-had once covered anything there was to email and still had been small
+had covered anything there was to email and still had been small
-and simple.)
+and simple.
-Then the essential complexity of email increased.
+Later, the essential complexity of email increased.
 (Essential complexity is the complexity defined by the problem itself.\0
 .[[
 brooks no silver bullet
 .]])
 Email systems reacted to this change: They grew.
-RFCs started to introduce mail agents and separated the various tasks
+RFCs started to introduce the concept of mail agents to separate the
-because the existing tasks became more extensive and new tasks appeared.
+various tasks because they became more extensive and new tasks appeared.
-Again, email systems grew, or they split parts off.
+As the mail systems grew even more, parts were split off.
-In nmh, for instance, the POP server, which the original MH had included,
+In nmh, for instance, the POP server, which was included in the original
-was removed.
+MH, was removed.
-Now is the time to go one step further and remove the MSA and MRA, too.
+Now is the time to go one step further and split the MSA and MRA off, too.
 Not only does this decrease the code size of the project,
 but, more important, it unburdens mmh of the whole field of
 message transfer with all its implications for the project.
-There's no more need to concern with changes in network transfer.
+There is no more need to concern with changes in network transfer.
 This independence is received by depending on an external program
 that covers the field.
 Today, this is a reasonable exchange.
 .P
-Function can be added in three different ways:
+Functionality can be added in three different ways:
 .BU
 Implementing the function originally in the project.
 .BU
 Depending on a library that provides the function.
 .BU
 but possibly limit the information exchange.
 External libraries are stronger connected than external programs,
 thus information can be exchanged more flexible.
 Adding code to a project increases maintenance work.
 .\" XXX ref
-Implementing complex functions originally in the project will add
+Implementing complex functions originally in the project adds
 a lot of code.
 This should be avoided if possible.
 Hence, the dependencies only change in kind, not in their existence.
 In mmh, library dependencies on
 .Pn libsasl2
 .I mpop
 and
 .I fdm .
-.H2 "Removal of non-MUA Tools
+.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
 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.
-On removing these tools, the project shall become more stream-lined
+By removing these tools, the project shall become more stream-lined
 and focused.
 In mmh the following tools are not available anymore:
 .BU
 .Pn conflict
 was removed
 because its use case of writing to the user's terminal
 on receiving of mail is obsolete.
 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 a terminals is hardly ever wanted today.
+Writing directly to terminals is hardly ever wanted today.
 If though one wants to have it this way, the standard tool
 .Pn write
 can be used in a way similar to:
 .VS
 scan -file - | write `id -un`
 .Pn msgchk
 provided hardly more information than:
 .VS
 ls -l /var/mail/meillo
 VE
-It did distinguished between old and new mail, but
+It did distinguish between old and new mail, but
-this detail information and can be retrieved with
+this detail information can be retrieved with
 .Pn stat (1),
 too.
-A very small shell script could be written to output the information
+A small shell script could be written to print the information
 in a similar way, if truly necessary.
 As mmh's
 .Pn inc
 only incorporates mail from the user's local maildrop,
 and thus no data transfers over slow networks are involved,
 .Pn vmh
 and
 .Pn wmh ,
 saved more than 7\|000 lines of C code \(en
 about 15\|% of the project's original source code amount.
-.P
+Having less code \(en with equal readability, of course \(en
-Having less code (with equal readability, of course)
 for the same functionality is an advantage.
 Less code means less bugs and less maintenance work.
 As
 .Pn rcvtty
 and
 .P
 Finally, there's
 .Pn slocal .
 .Pn slocal
 is an MDA and thus not directly MUA-related.
-It should be removed, because including it is a violation
+It should be removed from mmh, because including it conflicts with
-of the idea that mmh is a MUA only.
+the idea that mmh is a MUA only.
-It should become a separate project.
+.Pn slocal
+should rather become a separate project.
 However,
 .Pn slocal
 provides rule-based processing of messages, like filing them into
 different folders, which is otherwise not available in mmh.
 Although
 .Pn slocal
 does neither pull in dependencies nor does it include a separate
-technical area (cf. Sec. XXX),
+technical area (cf. Sec. XXX), still,
-still it accounts for about 1\|000 lines of code that need to be maintained.
+it 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.
 This would cut the strong connection between the MUA mmh and the MDA
 .Pn slocal .
 For anyone not using MH,
 .Pn slocal
 would become yet another independent MDA, like
 .I procmail .
-The need to install a complete MH system to have
+Then
 .Pn slocal
-would be gone.
+could be installed without the complete MH system.
 Likewise, mmh users could decide to use
 .I procmail
 without having a second, unused MDA,
 .Pn slocal ,
 installed.
-That's conceptionally the best solution.
+That appears to be conceptionally the best solution.
 Yet,
 .Pn slocal
 is not split off.
-I feel unsure with removing it from mmh.
+I defer the decision over
-Hence, I defer the decision over
-.Pn slocal .
-In the meanwhile
 .Pn slocal
-does not hurt because it is unrelated to the rest of mmh.
+in need for deeper investigation.
+In the meanwhile, it remains part of mmh.
+That does not hurt because
+.Pn slocal
+is unrelated to the rest of the project.
 .H2 "\fLshow\fP and \fPmhshow\fP
 .P
 Since the very beginning \(en already in the first concept paper \(en
 .Pn show
 mapped message numbers and sequences to files and invoked
 .Pn mhl
 to have the files formatted.
 With MIME, this approach wasn't sufficient anymore.
-MIME messages can consist of multiple parts, some of which aren't
+MIME messages can consist of multiple parts. Some parts are not
-directly displayable, further more text content might be encoded in
+directly displayable and text content might be encoded in
 foreign charsets.
 .Pn show 's
 understanding of messages and
 .Pn mhl 's
 display capabilities couldn't cope with the task any longer.
 to ensure that the programs behaved in a similar way,
 because they were used like a single tool.
 Different behavior would have surprised the user.
 .P
 Today, non-MIME messages are rather seen to be a special case of
-MIME messages, although it's the other way round.
+MIME messages, although it is the other way round.
 As
 .Pn mhshow
 had already be able to display non-MIME messages, it appeared natural
 to drop
 .Pn show
 .Pn show .
 But there is no chance;
 supporting MIME demands for higher essential complexity.
-.H2 "Removal of Configure Options
+.H2 "Configure Options
 .P
 Customization is a double-edged sword.
 It allows better suiting setups, but not for free.
 There is the cost of code complexity to be able to customize.
 There is the cost of less tested setups, because there are
 more possible setups and especially corner-cases.
 And, there is the cost of choice itself.
 The code complexity directly affects the developers.
 Less tested code affects both, users and developers.
 The problem of choice affects the users, for once by having to
-choose, but also by complexer interfaces that require more documentation.
+choose, but also by more complex interfaces that require more documentation.
 Whenever options add little advantages, they should be considered for
 removal.
 I have reduced the number of project-specific configure options from
 fifteen to three.
 Still, conditional compilation of a code base creates variations
 of the original program.
 More variations require more testing and maintenance work.
 .P
 Two other options only specified default configuration values:
-.Sw --with-mts=[smtp|sendmail]
+.Sw --with-mts
-defined the default transport service.
+defined the default transport service, either
+.Ar smtp
+or
+.Ar sendmail .
 In mmh this fixed to
 .Ar sendmail .
 .Ci f6aa95b724fd8c791164abe7ee5468bf5c34f226
 With
-.Sw --with-smtpservers=[server1...]
+.Sw --with-smtpservers
 default SMTP servers for the
 .Ar smtp
 transport service could be specified.
 .Ci 128545e06224233b7e91fc4c83f8830252fe16c9
 Both of them became irrelevant.
 to change the default to the hash symbol `\f(CW#\fP'.
 The choice was probably personal preference, because first, the
 option was named
 .Sw --with-backup-prefix.
 and had the prefix symbol as argument.
-Because giving the hash symbol as argument caused to many problems
+But giving the hash symbol as argument caused too many problems
-for configure,
+for Autoconf,
-the option was limited to use the hash symbol as the default prefix.
+thus the option was limited to use the hash symbol as the default prefix.
-This makes me believe, that the choice for the hash was personal preference.
+This supports the assumption, that the choice for the hash was
-Being it related or not, words that start with the hash symbol
+personal preference only.
+Being related or not, words that start with the hash symbol
 introduce a comment in the Unix shell.
 Thus, the command line
 .Cl "rm #13 #15
 calls
 .Pn rm
 without arguments because the first hash symbol starts the comment
 that reaches until the end of the line.
 To delete the backup files,
 .Cl "rm ./#13 ./#15"
 needs to be used.
-Using the hash as backup prefix can be seen as a precaution agains
+Using the hash as backup prefix can be seen as a precaution against
 data loss.
 .P
 I removed the configure option but added the profile entry
 .Pe backup-prefix ,
 which allows to specify an arbitrary string as backup prefix.
 .P
 Eventually, however, the new trash folder concept
 .Cf "Sec. XXX
 obsoleted the concept of the backup prefix completely.
 .Ci 8edc5aaf86f9f77124664f6801bc6c6cdf258173
-(Well, there still are corner-cases to remove until the backup
+.\" (Well, there still are corner-cases to remove until the backup
-prefix can be laid to rest, eventually.)
+.\" prefix can be laid to rest, eventually.)
 .\" FIXME: Do this work in the code!
 .U3 "Editor and Pager
 .P
 The two configure options
 .Ev PAGER
 environment variables,
 the new behavior confirms better to the common style on Unix systems.
 Additionally, the new approach is more uniform and clearer to users.
-.U3 "Locale
-.P
-The configure option
-.Sw --disable-locale
-was removed because POSIX provides locale support and there's
-hardly any need to disable locale support.
-.Ci ccf4f175ef4c4e7522f9510a4a1149c15d810dd9
 .U3 "ndbm
 .P
 .Pn slocal
 used to depend on
 to suppress delivering the same message to the same user twice.
 (This features was enabled by the
 .Sw -suppressdup
 switch.)
 .P
-A variety of version of the database library exist.
+A variety of versions of the database library exist.
 .[
 wolter unix incompat notes dbm
 .]
 Complicated autoconf code was needed to detect them correctly.
 Further more, the configure switches
 This option is likely to stay.
-.H2 "Removal of Switches
+.H2 "Command Line Switches
 .P
 The command line switches of MH tools follow the X Window style.
 They are words, introduced by a single dash.
 For example:
 .Cl "-truncate" .
 .P
 Fig. XXX
 .\" XXX Ref
 displays the number of switches for each of the tools that is available
 in both, nmh and mmh.
-Visible as well as hidden switches were counted,
+The tools are sorted by the number of switches they had in nmh.
+Visible and hidden switches were counted,
 but not the generic help and version switches.
 Whereas in the beginning of the project, the average tool had 11 switches,
 now it has no more than 5 \(en only half as many.
 If the `no' switches and similar inverse variant are folded onto
-their counter-parts, the average tool has 8 switches in pre-mmh to 4 now.
+their counter-parts, the average tool had 8 switches in pre-mmh times and
+has 4 now.
 The total number of functional switches in mmh dropped from 465
 to 234.
 .KS
 .in 1c
 the number of switches per command.
 .U3 "Draft Folder Facility
 .P
-A change early in the project was the completely transition from
+A change early in the project was the complete transition from
 the single draft message to the draft folder facility.
 .Ci 337338b404931f06f0db2119c9e145e8ca5a9860
-The draft folder facility was introduced in the mid-Eighties.
+The draft folder facility was introduced in the mid-Eighties, when
-(Rose and Romine called it a ``relatively new feature''
+Rose and Romine called it a ``relatively new feature''.
 .[
 rose romine real work
 .]
-in 1985.)
 Since then, the facility had existed but was deactivated by default.
 The default activation and the related rework of the tools made it
 possible to remove the
 .Sw -[no]draftfolder ,
 and
 .U3 "Inplace Editing
 .P
 .Pn anno
 had the switches
 .Sw -[no]inplace
-to either annotate the message inplace and thus preserve hard links,
+to either annotate the message in place and thus preserve hard links,
 or annotate a copy to replace the original message, breaking hard links.
 Following the assumption that linked messages should truly be the
 same message, and annotating it should not break the link, the
 .Sw -[no]inplace
 switches were removed and the previous default
 .U3 "MIME Tools
 .P
 The MIME tools, which were once part of
-.Pn mhn ,
+.Pn mhn
+[sic!],
 had several switches that added little practical value to the programs.
 The
 .Sw -[no]realsize
 switches of
 .Pn mhbuild
 .U3 "Suppressing Edits or the WhatNow Shell
 .P
 The
 .Sw -noedit
-switches of
+switch of
 .Pn comp ,
 .Pn repl ,
 .Pn forw ,
 .Pn dist ,
 and
 occurring.)
 .QE
 .P
 Effectively, the
 .Sw -nowhatnowproc
-switch stored a copy of the form file into the draft folder.
+switch creates only a draft message.
 As
 .Cl "-whatnowproc true
 causes the same behavior, the
 .Sw -nowhatnowproc
 switch was removed for being redundant.
-Likely, however, the intention for specifying
+Likely, the
 .Sw -nowhatnowproc
-is sending a fully prepared form file at once.
+switch was intended to be used by front-ends.
-This can be done with
-.Cl "-whatnowproc send" .
 .U3 "Compatibility Switches
 .BU
 The hidden
 .H1 "Modernizing
-.H2 "Removal of Code Relicts
+.H2 "Code Relicts
 .P
 The code base of mmh originates from the late Seventies,
 had been extensively
 worked on in the mid Eighties, and had been partly reorganized and extended
 in the Nineties. Relicts of all those times had gathered in the code base.
 foo
-.H1 "Code style
+.H1 "Code Style
 .P
 foo
 .H2 "Standard Code

Mercurial > docs > master

comparison ch03.roff @ 100:6ae7dc4a3a02