docs/master

changeset 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
files colophon.roff discussion.roff intro.roff preface.roff summary.roff
diffstat 5 files changed, 42 insertions(+), 31 deletions(-) [+]
line diff
     1.1 --- a/colophon.roff	Wed Jul 11 00:00:34 2012 +0200
     1.2 +++ b/colophon.roff	Wed Jul 11 09:24:47 2012 +0200
     1.3 @@ -56,7 +56,7 @@
     1.4  Apart from that, follow the scientific custom:
     1.5  Quote and acknowledge the reference.
     1.6  
     1.7 -.sp 4c
     1.8 +.sp 3c
     1.9  .LP
    1.10  Dijkstra's words on page
    1.11  .Cf dijkstra.page
     2.1 --- a/discussion.roff	Wed Jul 11 00:00:34 2012 +0200
     2.2 +++ b/discussion.roff	Wed Jul 11 09:24:47 2012 +0200
     2.3 @@ -274,7 +274,7 @@
     2.4  .H2 "Non-MUA Tools
     2.5  .P
     2.6  One goal of mmh is to remove the tools that are not part of the MUA's task.
     2.7 -Further more, any tools that do not significantly improve the MUA's job
     2.8 +Furthermore, any tools that do not significantly improve the MUA's job
     2.9  should be removed.
    2.10  Loosely related and rarely used tools distract from the lean appearance.
    2.11  They require maintenance work without adding much to the core task.
    2.12 @@ -823,7 +823,7 @@
    2.13  wolter unix incompat notes dbm
    2.14  .]
    2.15  Complicated autoconf code was needed to detect them correctly.
    2.16 -Further more, the configure switches
    2.17 +Furthermore, the configure switches
    2.18  .Sw --with-ndbm=ARG
    2.19  and
    2.20  .Sw --with-ndbmheader=ARG
    2.21 @@ -898,7 +898,7 @@
    2.22  .I fakeusername
    2.23  mapping, based on the password file's GECOS field.
    2.24  The man page
    2.25 -.Mp mh-tailor(5)
    2.26 +.Mp mh-tailor (5)
    2.27  described the use case as being the following:
    2.28  .QS
    2.29  This is useful if you want the messages you send to always
    2.30 @@ -913,7 +913,7 @@
    2.31  the best location to do such global rewrites is there.
    2.32  Besides, the MTA is conceptionally the right location because it
    2.33  does the reverse mapping for incoming mail (aliasing), too.
    2.34 -Further more, masquerading set up there is readily available for all
    2.35 +Furthermore, masquerading set up there is readily available for all
    2.36  mail software on the system.
    2.37  Hence, mmailid masquerading was removed.
    2.38  .Ci 0836c8000ccb34b59410ef1c15b1b7feac70ce5f
    2.39 @@ -1880,7 +1880,7 @@
    2.40  The mind model of email attachments is unrelated to MIME.
    2.41  Although the MIME RFCs (2045 through 2049) define the technical
    2.42  requirements for having attachments, they do not mention the word
    2.43 -``attachment''.
    2.44 +attachment.
    2.45  Instead of attachments, MIME talks about ``multi-part message bodies''
    2.46  [RFC\|2045], a more general concept.
    2.47  Multi-part messages are messages
    2.48 @@ -2428,7 +2428,7 @@
    2.49  Both scripts were written for nmh, hence they needed to be adjust
    2.50  according to the differences between nmh and mmh.
    2.51  For instance, they use the backup prefix no longer.
    2.52 -Further more, compatibility support for old PGP features was dropped.
    2.53 +Furthermore, compatibility support for old PGP features was dropped.
    2.54  .P
    2.55  The integrated message signing and encrypting support is one of the
    2.56  most recent features in mmh.
    2.57 @@ -2608,7 +2608,7 @@
    2.58  If this new message would be removed as well,
    2.59  then the backup of the former message is overwritten.
    2.60  Hence, the ability to restore removed messages did not only depend on
    2.61 -the ``sweeping cron job'' but also on the removing of further messages.
    2.62 +the sweeping cron job but also on the removing of further messages.
    2.63  It is undesirable to have such obscure and complex mechanisms.
    2.64  The user should be given a small set of clear assertions, such as
    2.65  ``Removed files are restorable within a seven-day grace time.''
    2.66 @@ -2619,7 +2619,7 @@
    2.67  In practice, the real mechanism is unclear to the user.
    2.68  The consequences of further removals are not obvious.
    2.69  .P
    2.70 -Further more, the backup files are scattered within the whole mail storage.
    2.71 +Furthermore, the backup files are scattered within the whole mail storage.
    2.72  This complicates managing them.
    2.73  It is possible with the help of
    2.74  .Pn find ,
    2.75 @@ -2928,7 +2928,11 @@
    2.76  to
    2.77  .Fu is_native_charset() .
    2.78  .Ci 8d77b48284c58c135a6b2787e721597346ab056d
    2.79 -The same change fixed a violation of ``Be accurate'' as well.
    2.80 +The same change fixed a violation of ``Be accurate''
    2.81 +.[ [
    2.82 +kernighan pike practice of programming
    2.83 +.], p. 4]
    2.84 +as well.
    2.85  The code did not match the expectation the function suggested,
    2.86  as it, for whatever reason, only compared the first ten characters
    2.87  of the charset name.
    2.88 @@ -2995,6 +2999,9 @@
    2.89  .P
    2.90  At the end of their chapter on style,
    2.91  Kernighan and Pike ask: ``But why worry about style?''
    2.92 +.[ [
    2.93 +kernighan pike practice of programming
    2.94 +.], p. 28]
    2.95  Following are two examples of structural rework that show
    2.96  why style is important in the first place.
    2.97  
    2.98 @@ -3345,7 +3352,7 @@
    2.99  MH tools read the profile right after starting up,
   2.100  as it contains the location of the user's mail storage
   2.101  and similar settings that influence the whole setup.
   2.102 -Further more, the profile contains the default switches for the tools,
   2.103 +Furthermore, the profile contains the default switches for the tools,
   2.104  hence, it must be read before the command line switches are processed.
   2.105  .P
   2.106  For historic reasons, some MH tools did not read the profile and context.
   2.107 @@ -3357,10 +3364,10 @@
   2.108  .Pn slocal .
   2.109  The reason why these tools ignored the profile were not clearly stated.
   2.110  During the discussion on the nmh-workers mailing list,
   2.111 +David Levine posted an explanation, quoting John Romine:
   2.112  .[
   2.113  nmh-workers levine post profile
   2.114  .]
   2.115 -David Levine posted an explanation, quoting John Romine:
   2.116  .QS
   2.117  I asked John Romine and here's what he had to say, which
   2.118  agrees and provides an example that convinces me:
   2.119 @@ -3476,10 +3483,10 @@
   2.120  Then Rose's motivation behind the decision that
   2.121  .Pn post
   2.122  ignores the profile, as quoted by Jeffrey Honig,
   2.123 +would have become possible:
   2.124  .[
   2.125  nmh-workers post profile
   2.126  .]
   2.127 -would have become possible:
   2.128  .QS
   2.129  when you run mh commands in a script, you want all the defaults to be
   2.130  what the man page says.
   2.131 @@ -3976,7 +3983,7 @@
   2.132  I learned about the easy and the difficult parts.
   2.133  Code is easy to understand if the influenced code area is small
   2.134  and its boundaries are strictly defined.
   2.135 -Further more, the code needs to solve the problem in a straight-forward way.
   2.136 +Furthermore, the code needs to solve the problem in a straight-forward way.
   2.137  .P
   2.138  .\" XXX move this paragraph somewhere else?
   2.139  Reading
   2.140 @@ -4019,6 +4026,7 @@
   2.141  .P
   2.142  But the real problem is another:
   2.143  Nmh violates the golden ``one tool, one job'' rule of the Unix philosophy.
   2.144 +.\" XXX ref
   2.145  Understanding
   2.146  .Pn comp
   2.147  requires understanding
   2.148 @@ -4068,6 +4076,7 @@
   2.149  No longer should we sacrifice readability or conceptional beauty.
   2.150  No longer should we violate the Unix philosophy's ``one tool, one job''
   2.151  guideline.
   2.152 +.\" XXX ref
   2.153  No longer should we keep speed improvements that became unnecessary.
   2.154  .P
   2.155  Therefore, mmh's
     3.1 --- a/intro.roff	Wed Jul 11 00:00:34 2012 +0200
     3.2 +++ b/intro.roff	Wed Jul 11 09:24:47 2012 +0200
     3.3 @@ -11,7 +11,7 @@
     3.4  This chapter introduces MH, its history, concepts and how it is used.
     3.5  It describes nmh's code base and community to give the reader
     3.6  a better understanding of the state of mmh when it started off.
     3.7 -Further more, this chapter outlines the mmh project itself,
     3.8 +Furthermore, this chapter outlines the mmh project itself,
     3.9  describing the motivation for it and its goals.
    3.10  
    3.11  
    3.12 @@ -31,8 +31,8 @@
    3.13  .P
    3.14  In 1977 at RAND Corporation, Norman Shapiro and Stockton Gaines
    3.15  proposed the design
    3.16 -of a new mail handling system, called ``Mail Handler'' (MH),
    3.17 -to superseed RAND's old monolithic ``Mail System'' (MS).
    3.18 +of a new mail handling system, called \fIMail Handler\fP (MH),
    3.19 +to superseed RAND's old monolithic \fIMail System\fP (MS).
    3.20  Two years later, in 1979, Bruce Borden took the proposal and implemented a
    3.21  prototype of MH.
    3.22  Before the prototype's existence, the concept was
    3.23 @@ -53,7 +53,7 @@
    3.24  email standard.
    3.25  .P
    3.26  In the nineties, the Internet became popular and in December 1996,
    3.27 -Richard Coleman initiated the ``New Mail Handler'' (nmh) project.
    3.28 +Richard Coleman initiated the \fINew Mail Handler\fP (nmh) project.
    3.29  Nmh is a fork of MH 6.8.3 and bases strongly on the
    3.30  \fILBL changes\fP by Van Jacobson, Mike Karels and Craig Leres.
    3.31  Colman intended to modernize MH and improve its portability and
    3.32 @@ -111,7 +111,7 @@
    3.33  .P
    3.34  The system is well scriptable and extensible.
    3.35  New MH tools are built out of or on top of existing ones quickly.
    3.36 -Further more, MH encourages the user to tailor, extend and automate the system.
    3.37 +Furthermore, MH encourages the user to tailor, extend and automate the system.
    3.38  As the MH tool chest was modeled after the Unix tool chest, the
    3.39  properties of the latter apply to the former as well.
    3.40  
     4.1 --- a/preface.roff	Wed Jul 11 00:00:34 2012 +0200
     4.2 +++ b/preface.roff	Wed Jul 11 09:24:47 2012 +0200
     4.3 @@ -116,19 +116,19 @@
     4.4  Good Unix shell knowledge is required, because MH relies fundamentally
     4.5  on the shell. Without the power of the shell, MH becomes a motorcycle
     4.6  without winding roads: boring.
     4.7 -Introductions to Unix and its shell can be found in ``The UNIX Programming
     4.8 -Environment'' by Kernighan and Pike
     4.9 +Introductions to Unix and its shell can be found in \fIThe UNIX Programming
    4.10 +Environment\fP by Kernighan and Pike
    4.11  .[
    4.12  kernighan pike unix prog env
    4.13  .]
    4.14 -or ``The UNIX System'' by Bourne.
    4.15 +or \fIThe UNIX System\fP by Bourne.
    4.16  .[
    4.17  bourne unix system
    4.18  .]
    4.19  The reader is assumed to be a C programmer,
    4.20  but the document should be understandable otherwise, too.
    4.21  The definitive guide to C is Kernighan and Ritchie's
    4.22 -``The C Programming Language''.
    4.23 +\fIThe C Programming Language\fP.
    4.24  .[
    4.25  kernighan ritchie c prog lang
    4.26  .]
    4.27 @@ -146,25 +146,26 @@
    4.28  The reader is expected to know the format of email messages and
    4.29  the structure of email transfer systems, at least on a basic level.
    4.30  It's advisable to have cross-read the RFCs 821 and 822.
    4.31 -Further more, basic understanding of MIME is good to have.
    4.32 +Furthermore, basic understanding of MIME is good to have.
    4.33  The Wikipedia provides good introduction-level information about email.
    4.34  .P
    4.35  Frequent references to the Unix philosophy will be made.
    4.36  Gancarz has tried to sum it up in his book
    4.37 -``The UNIX Philosophy''.
    4.38 +\fIThe UNIX Philosophy\fP.
    4.39  .[
    4.40  gancarz unix phil
    4.41  .]
    4.42 -Even better, though less concrete, are ``The UNIX Programming Environment''
    4.43 +Even better, though less concrete, are \fIThe UNIX Programming
    4.44 +Environment\fP
    4.45  .[
    4.46  kernighan pike unix prog env
    4.47  .]
    4.48 -and ``The Practice of Programming''
    4.49 +and \fIThe Practice of Programming\fP
    4.50  .[
    4.51  kernighan pike practice of prog
    4.52  .]
    4.53  by Kernighan and Pike.
    4.54 -The term paper ``Why the Unix Philosophy still matters''
    4.55 +The term paper \fIWhy the Unix Philosophy still matters\fP
    4.56  .[
    4.57  why unix phil still matters schnalke
    4.58  .]
    4.59 @@ -173,7 +174,7 @@
    4.60  .P
    4.61  Although a brief introduction to MH is provided in Chapter 1, the reader
    4.62  is encouraged to have a look at the \fIMH Book\fP
    4.63 -``MH & nmh: Email for Users & Programmers'' by Jerry Peek.
    4.64 +\fIMH & nmh: Email for Users & Programmers\fP by Jerry Peek.
    4.65  .[
    4.66  peek mh
    4.67  .]
     5.1 --- a/summary.roff	Wed Jul 11 00:00:34 2012 +0200
     5.2 +++ b/summary.roff	Wed Jul 11 09:24:47 2012 +0200
     5.3 @@ -5,7 +5,7 @@
     5.4  and options that diverted from the main task of mmh, being an MUA.
     5.5  I have modernized the code base removing obsolete functions and
     5.6  activating modern features per default.
     5.7 -Further more, I improved the style by refactoring clumpsy code
     5.8 +Furthermore, I improved the style by refactoring clumpsy code
     5.9  and by defining or forcing clear concepts.
    5.10  All my work was motivated by Antoine de Saint Exupery's well-known
    5.11  statement:
    5.12 @@ -99,7 +99,8 @@
    5.13  of the result.
    5.14  .\" behind closed doors; talks I've given
    5.15  My work on mmh was independent of the nmh community.
    5.16 -This enabled me to follow my vision straight and thus produce
    5.17 +.\" XXX straight?
    5.18 +This enabled me to follow my vision straightforwardly and thus produce
    5.19  a result of greater pureness.
    5.20  .P
    5.21  Mmh shall be considered as an inspiration for the future development of nmh.