1.1 --- a/preface.roff	Thu Jul 12 00:19:09 2012 +0200
     1.2 +++ b/preface.roff	Thu Jul 12 00:39:41 2012 +0200
     1.3 @@ -1,12 +1,23 @@
     1.4  .H0 "Preface" no
     1.5  
     1.6  .P
     1.7 -I have discovered the mail client \fInmh\fP in fall 2009.
     1.8 -At that time I used \fImutt\fP, as many advanced Unix users do.
     1.9 +I have discovered the mail client \fInmh\fP
    1.10 +.[
    1.11 +nmh website homepage
    1.12 +.]
    1.13 +in fall 2009.
    1.14 +At that time I used \fImutt\fP,
    1.15 +.[
    1.16 +mutt website
    1.17 +.]
    1.18 +as many advanced Unix users do.
    1.19  When I read about nmh, its concepts convinced me at once.
    1.20  The transition from mutt to nmh was similar to beginning with
    1.21  file management in the Unix shell when being used to the
    1.22  \fImidnight commander\fP,
    1.23 +.[
    1.24 +midnight commander website
    1.25 +.]
    1.26  or like starting with vi when being used to modeless editors.
    1.27  Such a change is not trivial, but, in being convinced by the
    1.28  concepts and by having done similar transitions for file management
    1.29 @@ -22,8 +33,19 @@
    1.30  expectations were rather common for modern emailing.
    1.31  As a computer scientist and programmer, I wanted to improve the situation.
    1.32  .P
    1.33 -In spring 2010, I sent a message to the \fInmh-workers\fP mailing list,
    1.34 -asking for the possibility to offer a Google Summer of Code project for me.
    1.35 +In spring 2010, I sent a message
    1.36 +.[
    1.37 +nmh-workers gsoc
    1.38 +.]
    1.39 +to the \fInmh-workers\fP mailing list,
    1.40 +.[
    1.41 +nmh-workers mailing list website
    1.42 +.]
    1.43 +asking for the possibility to offer a Google Summer of Code
    1.44 +.[
    1.45 +google summer of code website
    1.46 +.]
    1.47 +project for me.
    1.48  Participating in the development of nmh in this manner appeared attractive
    1.49  to me, because I would have been able to work full time on nmh.
    1.50  Although the nmh community had reacted generally positive to the suggestion,
    1.51 @@ -35,7 +57,7 @@
    1.52  .[
    1.53  nmh-workers thread mta mua
    1.54  .]
    1.55 -I argued for the MTA of nmh to be removed.
    1.56 +I argued for the Mail Transfer Agent of nmh to be removed.
    1.57  In this fundamental question,
    1.58  my opinion differed from the opinion of most others.
    1.59  Sadly, besides the discussions, hardly any real work was done.
    1.60 @@ -48,7 +70,7 @@
    1.61  This brought me back to nmh.
    1.62  Richard Sandelman, an active nmh user, took care of the official basis.
    1.63  Juan Granda, an Argentine free software developer,
    1.64 -provided a computer with Internet connection.
    1.65 +organized a computer with Internet connection.
    1.66  Thanks to them, I was able to work on nmh during my three-month
    1.67  stay in Santiago del Estero, Argentina.
    1.68  Quickly it became obvious that I would not succeed with my main goal,
    1.69 @@ -60,7 +82,7 @@
    1.70  Instead, I improved the code base as I read through it.
    1.71  I found minor bugs for which I proposed fixes.
    1.72  Additionally, I improved the documentation in minor ways.
    1.73 -When I started with larger code changes,
    1.74 +When I started to work on larger code changes,
    1.75  I had to discover that the community was reluctant to change.
    1.76  Its wish for compatibility was much stronger than its
    1.77  wish for convenient out-of-the-box setups \(en in contrast to my opinion.
    1.78 @@ -72,14 +94,15 @@
    1.79  and I still was convinced that I wanted to continue to do so.
    1.80  .P
    1.81  Another half year later, the end of my studies came within reach.
    1.82 -I needed a topic for my master's thesis.
    1.83 +I needed to choose a topic for my master's thesis.
    1.84  Without question, I wanted to work on nmh.
    1.85  But not exactly on nmh, because I had accepted that its
    1.86  community has different goals than I have.
    1.87  Working on nmh would result in much discussion and, in consequence,
    1.88  little progress.
    1.89  After careful thought, I decided to start an experimental version of nmh.
    1.90 -I wanted to implement my own ideas of how an MH-like system should look like.
    1.91 +I wanted to implement my own ideas of how an MH-like system should
    1.92 +look like.
    1.93  I wanted to create a usable alternative version to be compared with
    1.94  the present state of nmh.
    1.95  Eventually, my work would be proven successful or not.
    1.96 @@ -88,8 +111,11 @@
    1.97  .U2 "Focus of this Document
    1.98  .P
    1.99  This document explains the design goals and implementation decisions
   1.100 -for mmh.
   1.101 -.\" XXX mmh taucht hier zum ersten mal auf.
   1.102 +for mmh,
   1.103 +.[
   1.104 +mmh website homepage
   1.105 +.]
   1.106 +an experimental version of nmh.
   1.107  It discusses technical, historical, social and philosophical considerations.
   1.108  On the technical side, this document
   1.109  explains how an existing project was streamlined by removing rough edges
   1.110 @@ -114,7 +140,8 @@
   1.111  .P
   1.112  The reader is expected to be familiar with Unix, C and emailing.
   1.113  Good Unix shell knowledge is required, because MH relies fundamentally
   1.114 -on the shell. Without the power of the shell, MH becomes a motorcycle
   1.115 +on the shell.
   1.116 +Without the power of the shell, MH becomes a motorcycle
   1.117  without winding roads: boring.
   1.118  Introductions to Unix and its shell can be found in \fIThe UNIX Programming
   1.119  Environment\fP by Kernighan and Pike
   1.120 @@ -145,9 +172,13 @@
   1.121  because large parts of the source code are old.
   1.122  The reader is expected to know the format of email messages and
   1.123  the structure of email transfer systems, at least on a basic level.
   1.124 -It's advisable to have cross-read the RFCs 821 and 822.
   1.125 -Furthermore, basic understanding of MIME is good to have.
   1.126 +It's advisable to have cross-read RFC\|821 and RFC\|822.
   1.127 +Furthermore, basic understanding of MIME (RFC\|2045\(en2049)
   1.128 +is good to have.
   1.129  The Wikipedia provides good introduction-level information about email.
   1.130 +.[
   1.131 +wikipedia email
   1.132 +.]
   1.133  .P
   1.134  Frequent references to the Unix philosophy will be made.
   1.135  Gancarz has tried to sum it up in his book
   1.136 @@ -169,11 +200,12 @@
   1.137  .[
   1.138  why unix phil still matters schnalke
   1.139  .]
   1.140 -by myself
   1.141 -provides an overview on the philosophy, including a case study of MH.
   1.142 +by myself provides an overview on the philosophy,
   1.143 +including a case study of MH.
   1.144  .P
   1.145 -Although a brief introduction to MH is provided in Chapter 1, the reader
   1.146 -is encouraged to have a look at the \fIMH Book\fP
   1.147 +Although a brief introduction to MH is provided in Section
   1.148 +.Cf mh ,
   1.149 +the reader is encouraged to have a look at
   1.150  \fIMH & nmh: Email for Users & Programmers\fP by Jerry Peek.
   1.151  .[
   1.152  peek mh
   1.153 @@ -204,8 +236,8 @@
   1.154  a look into the future of the mmh project.
   1.155  .P
   1.156  .I "Italic font
   1.157 -is used to emphasize new terms, and to name software projects and
   1.158 -man pages.
   1.159 +is used to emphasize new terms, and for names of software projects,
   1.160 +literature, and man pages.
   1.161  .CW "Constant width font
   1.162  is used to denote names of programs, files,
   1.163  functions, command lines, code excrepts, program input and output.
   1.164 @@ -216,18 +248,31 @@
   1.165  .Pn cat ,
   1.166  which is in section one of the Unix manual.
   1.167  Internet technologies are specified by \fIRequests for Comments\fP (RFCs).
   1.168 -Throughout the document, they are referenced in this way ``RFC\|822''.
   1.169 +Throughout the document, they are referenced as ``RFC\|821''.
   1.170  A list of relevant RFCs is located at the end of the document.
   1.171 -References to literature are printed in backets, like
   1.172 +Literature is cited in backets, such as
   1.173  .[ ``[
   1.174  kernighan pike unix programming env
   1.175 -.]]'', within the text.
   1.176 -The full references are collected at the end of the document.
   1.177 +.]]''.
   1.178 +Citations of email messages and websites are in the same style
   1.179 +but distinguished by a prefix.
   1.180 +For example:
   1.181 +.[ ``[
   1.182 +website mmh
   1.183 +.]]''
   1.184 +and
   1.185 +.[ ``[
   1.186 +nmh-workers mmh announce
   1.187 +.]]''.
   1.188 +All references are collected at the end of the document.
   1.189  .P
   1.190  This document describes practical programming work.
   1.191 -The code of mmh is managed by the
   1.192 +The code of mmh is managed with the
   1.193  .Pn git
   1.194  version control system.
   1.195 +.[
   1.196 +git website
   1.197 +.]
   1.198  All code changes were checked in.
   1.199  In the discussions, references to corresponding code changes are printed
   1.200  as ``\c
   1.201 @@ -239,9 +284,15 @@
   1.202  replacing `\f(CWXXX\fP' with the concrete hash value or any unique prefix.
   1.203  In this example:
   1.204  .Cl "git show 1a2b3c4" .
   1.205 -At the time of writing, changesets can be looked up online this way:
   1.206 +At the time of writing, changesets can be looked up online at:
   1.207  .CW "http://git.marmaro.de/?p=mmh;a=commitdiff;h=XXX" .
   1.208  But as we all know, URIs are always at risk to change.
   1.209 +.P
   1.210 +Whenever lines of code were determined, David A. Wheeler's \fIsloccount\fP
   1.211 +.[
   1.212 +sloccount website
   1.213 +.]
   1.214 +was used to measure the amount in a comparable way.
   1.215  
   1.216  
   1.217  .U2 "Acknowledgments