docs/master: discussion.roff comparison

comparison discussion.roff @ 181:eb6eeb10afd5

Various stuff: Checked quotes, s/further more/furthermore/, etc

author	markus schnalke <meillo@marmaro.de>
date	Wed, 11 Jul 2012 09:24:47 +0200
parents	731e747a805b
children	764738b17b74

comparison

equal deleted inserted replaced

-:731e747a805b
+:eb6eeb10afd5
 .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 do not significantly improve the MUA's job
+Furthermore, any tools that do not 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.
 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
+Furthermore, the configure switches
 .Sw --with-ndbm=ARG
 and
 .Sw --with-ndbmheader=ARG
 were added to help with difficult setups that would
 not be detected automatically or correctly.
 .I username
 to
 .I fakeusername
 mapping, based on the password file's GECOS field.
 The man page
-.Mp mh-tailor(5)
+.Mp mh-tailor (5)
 described the use case as being the following:
 .QS
 This is useful if you want the messages you send to always
 appear to come from the name of an MTA alias rather than your
 actual account name.  For instance, many organizations set up
 .P
 As mmh sends outgoing mail via the local MTA only,
 the best location to do such global rewrites is there.
 Besides, the MTA is conceptionally the right location because it
 does the reverse mapping for incoming mail (aliasing), too.
-Further more, masquerading set up there is readily available for all
+Furthermore, masquerading set up there is readily available for all
 mail software on the system.
 Hence, mmailid masquerading was removed.
 .Ci 0836c8000ccb34b59410ef1c15b1b7feac70ce5f
 .P
 The
 .H2 "Attachments
 .P
 The mind model of email attachments is unrelated to MIME.
 Although the MIME RFCs (2045 through 2049) define the technical
 requirements for having attachments, they do not mention the word
-``attachment''.
+attachment.
 Instead of attachments, MIME talks about ``multi-part message bodies''
 [RFC\|2045], a more general concept.
 Multi-part messages are messages
 ``in which one or more different
 sets of data are combined in a single body''
 is planned but not realized yet.
 .P
 Both scripts were written for nmh, hence they needed to be adjust
 according to the differences between nmh and mmh.
 For instance, they use the backup prefix no longer.
-Further more, compatibility support for old PGP features was dropped.
+Furthermore, compatibility support for old PGP features was dropped.
 .P
 The integrated message signing and encrypting support is one of the
 most recent features in mmh.
 It has not yet had the time to mature.
 User feedback and personal experience need to be accumulated to
 .Fn 6
 then.
 If this new message would be removed as well,
 then the backup of the former message is overwritten.
 Hence, the ability to restore removed messages did not only depend on
-the ``sweeping cron job'' but also on the removing of further messages.
+the sweeping cron job but also on the removing of further messages.
 It is undesirable to have such obscure and complex mechanisms.
 The user should be given a small set of clear assertions, such as
 ``Removed files are restorable within a seven-day grace time.''
 With the addition ``... unless a message with the same name in the
 same folder is removed before.'' the statement becomes complex.
 A user will hardly be able to keep track of any removal to know
 if the assertion still holds true for a specific file.
 In practice, the real mechanism is unclear to the user.
 The consequences of further removals are not obvious.
 .P
-Further more, the backup files are scattered within the whole mail storage.
+Furthermore, the backup files are scattered within the whole mail storage.
 This complicates managing them.
 It is possible with the help of
 .Pn find ,
 but everything would be more convenient
 if the deleted messages would be collected in one place.
 One application of this rule was the rename of
 .Fu check_charset()
 to
 .Fu is_native_charset() .
 .Ci 8d77b48284c58c135a6b2787e721597346ab056d
-The same change fixed a violation of ``Be accurate'' as well.
+The same change fixed a violation of ``Be accurate''
+.[ [
+kernighan pike practice of programming
+.], p. 4]
+as well.
 The code did not match the expectation the function suggested,
 as it, for whatever reason, only compared the first ten characters
 of the charset name.
 .P
 More important than using active names is using descriptive names.
 They are more difficult to do but lead to larger improvements,
 especially as they influence the outer shape of the tools as well.
 .P
 At the end of their chapter on style,
 Kernighan and Pike ask: ``But why worry about style?''
+.[ [
+kernighan pike practice of programming
+.], p. 28]
 Following are two examples of structural rework that show
 why style is important in the first place.
 .U3 "Rework of \f(CWanno\fP
 .P
 The MH profile contains the configuration for the user-specific MH setup.
 MH tools read the profile right after starting up,
 as it contains the location of the user's mail storage
 and similar settings that influence the whole setup.
-Further more, the profile contains the default switches for the tools,
+Furthermore, the profile contains the default switches for the tools,
 hence, it must be read before the command line switches are processed.
 .P
 For historic reasons, some MH tools did not read the profile and context.
 Among them were
 .Pn post /\c
 .Pn mhmail ,
 and
 .Pn slocal .
 The reason why these tools ignored the profile were not clearly stated.
 During the discussion on the nmh-workers mailing list,
+David Levine posted an explanation, quoting John Romine:
 .[
 nmh-workers levine post profile
 .]
-David Levine posted an explanation, quoting John Romine:
 .QS
 I asked John Romine and here's what he had to say, which
 agrees and provides an example that convinces me:
 .QS
 My take on this is that
 By writing a clean-profile-wrapper, the concept could have been
 generalized orthogonally to the whole MH tool chest.
 Then Rose's motivation behind the decision that
 .Pn post
 ignores the profile, as quoted by Jeffrey Honig,
+would have become possible:
 .[
 nmh-workers post profile
 .]
-would have become possible:
 .QS
 when you run mh commands in a script, you want all the defaults to be
 what the man page says.
 when you run a command by hand, then you want your own defaults...
 .QE
 .P
 As I have read a lot in the code base during the last two years,
 I learned about the easy and the difficult parts.
 Code is easy to understand if the influenced code area is small
 and its boundaries are strictly defined.
-Further more, the code needs to solve the problem in a straight-forward way.
+Furthermore, the code needs to solve the problem in a straight-forward way.
 .P
 .\" XXX move this paragraph somewhere else?
 Reading
 .Pn rmm 's
 source code in
 .Fu exec()
 rather than arbitrary function calls.
 .P
 But the real problem is another:
 Nmh violates the golden ``one tool, one job'' rule of the Unix philosophy.
+.\" XXX ref
 Understanding
 .Pn comp
 requires understanding
 .Fn uip/annosbr.c
 and
 speed might even have been a must to prevent MH from being unusably slow.
 Whatever the reasons had been, today they are gone.
 No longer should we sacrifice readability or conceptional beauty.
 No longer should we violate the Unix philosophy's ``one tool, one job''
 guideline.
+.\" XXX ref
 No longer should we keep speed improvements that became unnecessary.
 .P
 Therefore, mmh's
 .Pn comp
 does no longer send messages.

Mercurial > docs > master

comparison discussion.roff @ 181:eb6eeb10afd5