docs/master

view preface.roff @ 82:ff4537327162

Mayor rework: Replaced .DS with .VS, a better verbatim environment. VS is no Keep. By translating characters in the typewriter fonts, we don't need to escape the minus, backtick and single quote characters.
author markus schnalke <meillo@marmaro.de>
date Wed, 06 Jun 2012 17:58:09 +0200
parents 01d06ca2eb1b
children 7d5b180de542
line source
1 .H0 "Preface" no
3 .P
4 I have discovered the mail client \fInmh\fP in September 2009.
5 At that time I used to use \fImutt\fP, as many advanced Unix users do.
6 When I read about nmh, its concepts had convinced me at once.
7 The transition from mutt to nmh was similar to
8 managing files in the Unix shell when being used to the
9 \fImidnight commander\fP,
10 or like editing with vi when being used to modeless editors.
11 Such a change is not trivial, but in being convinced by the
12 concepts and by having done similar transitions for file management
13 and editing already, it was not too difficult.
14 In contrast, setting up nmh to a convenient state became a tedious task
15 that took several months.
16 Once having nmh arranged to a convenient state, I enjoyed using it
17 because of its conceptional elegance and its scripting capabilities.
18 On the other hand, nevertheless, it still was
19 inconvenient for handling attachments, non-ASCII character encodings,
20 and similar features of modern emailing.
21 My setup demanded more and more additional configuration and helper scripts
22 to get nmh behave the way I wanted, although my
23 expectations were rather common for modern emailing.
24 In being a computer scientist and programmer,
25 I wanted to improve the situation.
26 .P
27 In Spring 2010, I asked on the \fInmh-workers\fP mailing list for the
28 possibility to offer a Google Summer of Code project for me.
29 Participating in the development of nmh this way appeared attractive to me,
30 because I would have been able to work full time on nmh as the project
31 could have been part of my official studies at university.
32 Although the nmh community had been generally positive on the suggestion,
33 the administrative work for a GSoC project had been to much to have
34 it realized.
35 Nontheless, my proposal had activated the nmh community.
36 In the following weeks, goals for nmh's future were discussed.
37 In these discussions, I became involved in the
38 question whether nmh should include mail transfer facilities.
39 .[
40 nmh-workers thread mta mua
41 .]
42 In this central point, my opinion differed from the opinion of most others.
43 I argued for the MTA facility of nmh to be removed.
44 Besides the discussions, hardly any real work was done.
45 Being unable to work on nmh in a way that would be
46 accepted as part of my official studies, I needed to choose another project.
47 .P
48 Half a year later, starting in August 2010,
49 I took one semester off to travel through Latin America.
50 During my time in Argentina, I planned to work on Free Software.
51 This brought me back to nmh.
52 Richard Sandelman, an active nmh user, cared for the official basis.
53 Juan Granda, an argentine Free Software developer,
54 provided a computer with Internet connection for my work.
55 Thanks to them, I was able to work on nmh during my three-month
56 stay in Santiago del Estero in Argentina.
57 Quickly it became obvious that I wouldn't succeed with my main goal:
58 improving the character encoding handling within the project.
59 One of its ramifications is the
60 missing transfer decoding of quoted text in replies.
61 As this is one of the most intricate parts of the system, the goal
62 was simply set too high.
63 Instead, I improved the code base as I read through it.
64 I found minor bugs for which I proposed fixes to the community.
65 In the same go, I improved the documentation in minor ways.
66 When I started with larger code changes,
67 I had to discover that the community was reluctant to change.
68 Its wish for compatibility was much stronger than its
69 wish for convenient out-of-the-box setups \(en in contrast to my opinion.
70 This led to long discussions, again.
71 I came to understand their point of view, but it was different to mine.
72 At the end of my three-month project, I had become familiar with
73 nmh's code base and community.
74 I had improved the project in minor ways,
75 and I still was convinced that I wanted to go on to do so.
76 .P
77 Another half year later, the end of my studies came within reach.
78 I needed a topic for my master's thesis.
79 No question, I wanted to work on nmh.
80 But well, not exactly on nmh, because I had accepted that the
81 nmh community has different goals than I have.
82 This would result in much discussion and thus little progress.
83 After careful thought, I decided to start an experimental version of nmh.
84 I wanted to implement my own ideas of how an MH-like system should look like.
85 I wanted to create a usable alternative version to be compared with
86 the present state of nmh.
87 Eventually, my work would be proven successful or not.
88 In any case, the nmh project would profit from my experiences.
90 .U2 "Focus of this Document
91 .P
92 This document explains the design goals and implementation decisions
93 for mmh.
94 It discusses technical, historical, social and philosophical considerations.
95 On the technical side, this document
96 explains how an existing project was stream-lined by removing rough edges
97 and exploiting the central concepts better.
98 On the historical
99 side, changes through time in the use cases and the email features,
100 as well as the reactions to them, are discussed.
101 Socially, this document describes the effects
102 and experiences of a newcomer with revolutionary aims entering an old
103 and matured software project.
104 Philosophical thoughts on style, mainly based to the Unix
105 philosophy, are present throughout the discussions.
106 The document describes the changes to nmh,
107 but as well, it clarifies my personal perception of the
108 concepts of MH and Unix, and explain my therefrom resulting point of view.
109 .P
110 This document is written for the community around MH-like mail systems,
111 including developers and users.
112 Despite the focus on MH-like systems, this document is may be precious
113 to anyone interested in the Unix philosophy and anyone in contact to
114 old software projects, be it code or community-related.
115 .P
116 The reader is expected to be well familiar with Unix, C and emailing.
117 Good Unix shell knowledge is required, because MH relies fundamentally
118 on the shell. Without the power of the shell, MH becomes a motorbike
119 without winding roads: boring.
120 Introductions to Unix and its shell can be found in ``The UNIX Programming
121 Environment'' by Kernighan and Pike
122 .[
123 kernighan pike unix prog env
124 .]
125 or ``The UNIX System'' by Bourne.
126 .[
127 bourne unix system
128 .]
129 The reader is assumed to be a C programmer,
130 but the document should be understandable otherwise, too.
131 The definitive guide to C is Kernighan and Ritchie's
132 ``The C Programming Language''.
133 .[
134 kernighan ritchie c prog lang
135 .]
136 Some book about system-level C programming can be helpful
137 additional literature. Rochkind and Curry have written such books.
138 .[
139 rochkind advanced unix prog
140 .]
141 .[
142 curry system prog
143 .]
144 As large parts of the source code are old,
145 old books are likely more helpful for understanding.
146 The reader is expected to know the format of email messages and
147 the structure of email transfer systems, at least on a basic level.
148 It's advisable to have cross-read the RFCs 821 and 822.
149 Further more, basic understanding of MIME is good to have.
150 The Wikipedia provides good introduction-level information to email.
151 .P
152 Frequent references to the Unix philosophy will be made.
153 Gancarz has tried to sum it up in his book
154 ``The UNIX Philosophy''.
155 .[
156 gancarz unix phil
157 .]
158 Even better, though less concrete, are ``The UNIX Programming Environment''
159 .[
160 kernighan pike unix prog env
161 .]
162 and ``The Practice of Programming''
163 .[
164 kernighan pike practice of prog
165 .]
166 by Kernighan and Pike.
167 The term paper ``Why the Unix Philosophy still matters''
168 .[
169 why unix phil still matters schnalke
170 .]
171 by myself
172 provides an overview on the philosophy, including a case study of MH.
173 .P
174 Although a brief introduction to MH is provided in Chapter 1, the reader
175 is encouraged to have a look at the \fIMH Book\fP
176 ``MH & nmh: Email for Users & Programmers'' by Jerry Peek.
177 .[
178 peek mh
179 .]
180 The current version is available freely on the Internet.
181 It is the definitive guide to MH and nmh.
182 .P
183 This document is neither a user's tutorial to mmh nor an introduction
184 to any of the topics covered.
185 The technical discussions are on an advanced level.
186 Nevertheless, as knowledge of the fundamental concepts is the most valuable
187 information a user can acquire about some program or software system,
188 this document may be worth a read for non-developers as well.
191 .U2 "Organization
192 .P
193 Which font for what use.
194 Meaning of `foo(1)'.
195 RFCs.
196 .P
197 References to source code repository commits are printed as
198 .Ci 1a2b3c4 .
199 They can be looked up with
200 .Cl "git show XXX
201 on the command line or
202 online at
203 .CW "http://git.marmaro.de/?p=mmh;a=commitdiff;h=XXX" ,
204 replacing `\f(CWXXX\fP' with the hash value.
205 In this example:
206 .Cl "git show 1a2b3c4
207 or
208 .CW "http://git.marmaro.de/?p=mmh;a=commitdiff;h=1a2b3cd" .
209 Whereas the code repository will probably be available on the Internet
210 forever, a website URL is always at risk to change.
211 .P
212 This thesis is divided into XXX chapters, ...
213 .P
214 .I Chapter 1
215 introduces ...
216 .P
217 .I Chapter 2
218 describes ...
219 .P
220 .I Chapter 3
221 covers ...
224 .U2 "Acknowledgments
225 .P
226 To be written at the very end.