docs/master

view preface.roff @ 202:e417f510aaca

find changesets by author, revision, files, or words in the commit message
Reworked the MH example session.
author markus schnalke <meillo@marmaro.de>
date Thu, 12 Jul 2012 09:04:13 +0200
parents 5cd9bacdfcd3
children 9317d789cef9
line source
1 .H0 "Preface" no
2
3 .P
4 I have discovered the mail client \fInmh\fP
5 .[
6 nmh website homepage
7 .]
8 in fall 2009.
9 At that time I used \fImutt\fP,
10 .[
11 mutt website
12 .]
13 as many advanced Unix users do.
14 When I read about nmh, its concepts convinced me at once.
15 The transition from mutt to nmh was similar to beginning with
16 file management in the Unix shell when being used to the
17 \fImidnight commander\fP,
18 .[
19 midnight commander website
20 .]
21 or like starting with vi when being used to modeless editors.
22 Such a change is not trivial, but, in being convinced by the
23 concepts and by having done similar transitions for file management
24 and editing already, it was not too difficult.
25 In contrast, setting up nmh to a convenient state became a tedious task
26 that took several months.
27 Once having nmh arranged this way, I enjoyed using it
28 because of its conceptional elegance and its scripting capabilities.
29 Nevertheless, it was still inconvenient for handling attachments,
30 non-ASCII character encodings, and similar features of modern emailing.
31 My setup demanded more and more additional configuration and helper scripts
32 to have nmh behave the way I wanted; yet my
33 expectations were rather common for modern emailing.
34 As a computer scientist and programmer, I wanted to improve the situation.
35 .P
36 In spring 2010, I sent a message
37 .[
38 nmh-workers gsoc
39 .]
40 to the \fInmh-workers\fP mailing list,
41 .[
42 nmh-workers mailing list website
43 .]
44 asking for the possibility to offer a Google Summer of Code
45 .[
46 google summer of code website
47 .]
48 project for me.
49 Participating in the development of nmh in this manner appeared attractive
50 to me, because I would have been able to work full time on nmh.
51 Although the nmh community had reacted generally positive to the suggestion,
52 the administrative work for such a project would had been too much.
53 Nonetheless, my proposal had activated the nmh community.
54 In the following weeks, goals for nmh's future were discussed.
55 In these discussions, I became involved in the
56 question whether nmh should include mail transfer facilities.
57 .[
58 nmh-workers thread mta mua
59 .]
60 I argued for the Mail Transfer Agent of nmh to be removed.
61 In this fundamental question,
62 my opinion differed from the opinion of most others.
63 Sadly, besides the discussions, hardly any real work was done.
64 Being unable to work on nmh in a way that would be accepted at university
65 as part of my studies, I needed to choose another project.
66 .P
67 Half a year later, starting in August 2010,
68 I took one semester off to travel through Latin America.
69 During my time in Argentina, I wanted to work on free software.
70 This brought me back to nmh.
71 Richard Sandelman, an active nmh user, took care of the official basis.
72 Juan Granda, an Argentine free software developer,
73 organized a computer with Internet connection.
74 Thanks to them, I was able to work on nmh during my three-month
75 stay in Santiago del Estero, Argentina.
76 Quickly it became obvious that I would not succeed with my main goal,
77 to improve the character encoding handling.
78 (One of its ramifications is the
79 missing transfer decoding of quoted text in replies.)
80 As this is one of the most intricate parts of the system, the goal
81 was simply set too high.
82 Instead, I improved the code base as I read through it.
83 I found minor bugs for which I proposed fixes.
84 Additionally, I improved the documentation in minor ways.
85 When I started to work on larger code changes,
86 I had to discover that the community was reluctant to change.
87 Its wish for compatibility was much stronger than its
88 wish for convenient out-of-the-box setups \(en in contrast to my opinion.
89 This, once again, led to long discussions.
90 I came to understand their point of view, but it was different to mine.
91 At the end of my three-month project, I had become familiar with
92 nmh's code base and community,
93 I had improved the project in minor ways,
94 and I still was convinced that I wanted to continue to do so.
95 .P
96 Another half year later, the end of my studies came within reach.
97 I needed to choose a topic for my master's thesis.
98 Without question, I wanted to work on nmh.
99 But not exactly on nmh, because I had accepted that its
100 community has different goals than I have.
101 Working on nmh would result in much discussion and, in consequence,
102 little progress.
103 After careful thought, I decided to start an experimental version of nmh.
104 I wanted to implement my own ideas of how an MH-like system should
105 look like.
106 I wanted to create a usable alternative version to be compared with
107 the present state of nmh.
108 Eventually, my work would be proven successful or not.
109 In any case, the nmh project would profit from my experiences.
110
111 .U2 "Focus of this Document
112 .P
113 This document explains the design goals and implementation decisions
114 for mmh,
115 .[
116 mmh website homepage
117 .]
118 an experimental version of nmh.
119 It discusses technical, historical, social and philosophical considerations.
120 On the technical side, this document
121 explains how an existing project was streamlined by removing rough edges
122 and better exploitation of the central concepts.
123 On the historical side, changes through time are discussed,
124 regarding the use cases and the email features,
125 as well as the reactions to them.
126 Socially, this document describes the effects
127 and experiences of a newcomer with revolutionary aims entering an old
128 and matured software project.
129 Philosophical thoughts on style, mainly based on the Unix
130 philosophy, are present throughout the discussions.
131 The document describes the changes to nmh,
132 but as well, it clarifies my personal perception of the
133 concepts of MH and Unix, and explain my therefrom resulting point of view.
134 .P
135 This document is written for the community around MH-like mail systems,
136 including developers and users.
137 Despite the focus on MH-like systems, this document may be valuable
138 to anyone interested in the Unix philosophy and anyone in contact with
139 old software projects, be it code- or community-related.
140 .P
141 The reader is expected to be familiar with Unix, C and emailing.
142 Good Unix shell knowledge is required, because MH relies fundamentally
143 on the shell.
144 Without the power of the shell, MH becomes a motorcycle
145 without winding roads: boring.
146 Introductions to Unix and its shell can be found in \fIThe UNIX Programming
147 Environment\fP by Kernighan and Pike
148 .[
149 kernighan pike unix prog env
150 .]
151 or \fIThe UNIX System\fP by Bourne.
152 .[
153 bourne unix system
154 .]
155 The reader is assumed to be a C programmer,
156 but the document should be understandable otherwise, too.
157 The definitive guide to C is Kernighan and Ritchie's
158 \fIThe C Programming Language\fP.
159 .[
160 kernighan ritchie c prog lang
161 .]
162 A book about system-level C programming, such as those written by
163 Rochkind and Curry,
164 .[
165 rochkind advanced unix prog
166 .]
167 .[
168 curry system prog
169 .]
170 can be helpful as additional literature.
171 Old books are likely more helpful for understanding,
172 because large parts of the source code are old.
173 The reader is expected to know the format of email messages and
174 the structure of email transfer systems, at least on a basic level.
175 It's advisable to have cross-read RFC\|821 and RFC\|822.
176 Furthermore, basic understanding of MIME [RFC\|2045\(enRFC\|2049]
177 is good to have.
178 The Wikipedia provides good introduction-level information about email.
179 .[
180 wikipedia email
181 .]
182 .P
183 Frequent references to the Unix philosophy will be made.
184 Gancarz has tried to sum it up in his book
185 \fIThe UNIX Philosophy\fP.
186 .[
187 gancarz unix phil
188 .]
189 Even better, though less concrete, are \fIThe UNIX Programming
190 Environment\fP
191 .[
192 kernighan pike unix prog env
193 .]
194 and \fIThe Practice of Programming\fP
195 .[
196 kernighan pike practice of prog
197 .]
198 by Kernighan and Pike.
199 The term paper \fIWhy the Unix Philosophy still matters\fP
200 .[
201 why unix phil still matters schnalke
202 .]
203 by myself provides an overview on the philosophy,
204 including a case study of MH.
205 .P
206 Although a brief introduction to MH is provided in Section
207 .Cf mh ,
208 the reader is encouraged to have a look at
209 \fIMH & nmh: Email for Users & Programmers\fP by Jerry Peek.
210 .[
211 peek mh
212 .]
213 The current version is available freely on the Internet.
214 It is the definitive guide to MH and nmh.
215 .P
216 This document is neither a user's tutorial to mmh nor an introduction
217 to any of the topics covered.
218 The technical discussions are on an advanced level.
219 Nevertheless, as knowledge of the fundamental concepts is the most valuable
220 information a user can acquire about some program or software system,
221 this document may be worth a read for non-developers as well.
222
223
224 .U2 "Organization
225 .P
226 This thesis consists of three chapters.
227 Chapter 1 introduces into the topic, describing MH and explaining
228 the background and goals of the mmh project.
229 Chapter 2 discusses the work done in the project.
230 It is organized along the three major goals of the project, namely
231 streamlining, modernizing, and styling.
232 Not every change is described because that would bore the reader.
233 Instead, important changes and those standing for a set of similar
234 changes are described and discussed.
235 Chapter 3 finishes up by summarizing the achievements and taking
236 a look into the future of the mmh project.
237 .P
238 .I "Italic font
239 is used to emphasize new terms, and for names of software projects,
240 literature, and man pages.
241 .CW "Constant width font
242 is used to denote names of programs, files,
243 functions, command lines, code excerpts, program input and output.
244 .P
245 References to man pages are printed as ``\c
246 .Mp cat (1)''.
247 In this case it is a reference to the man page of
248 .Pn cat ,
249 which is in section one of the Unix manual.
250 Internet technologies are specified by \fIRequests for Comments\fP (RFCs).
251 Throughout the document, they are referenced similar to ``RFC\|821''.
252 A list of relevant RFCs is located at the end of the document.
253 Literature is cited in brackets, such as
254 .[ ``[
255 kernighan pike unix programming env
256 .]]''.
257 Citations of email messages and websites are in the same style
258 but distinguished by a prefix.
259 For example:
260 .[ ``[
261 website mmh
262 .]]''
263 and
264 .[ ``[
265 nmh-workers mmh announce
266 .]]''.
267 All references are collected at the end of the document.
268 .P
269 This document describes practical programming work.
270 The code of mmh is managed with the
271 .Pn git
272 version control system.
273 .[
274 git website
275 .]
276 All code changes were checked in.
277 In the discussions, references to corresponding code changes are printed
278 as ``\c
279 .Ci 1a2b3c4 ''.
280 The identifier is the seven-letter-prefix of the changeset hash value,
281 which is considered unique.
282 A change can be looked up in the repository, on the command line with
283 .Cl "git show XXX" ,
284 replacing `\f(CWXXX\fP' with the concrete hash value or any unique prefix.
285 In this example:
286 .Cl "git show 1a2b3c4" .
287 At the time of writing, changesets can be looked up online at:
288 .CW "http://git.marmaro.de/?p=mmh;a=commitdiff;h=XXX" .
289 But as we all know, URIs are always at risk to change.
290 .P
291 Whenever lines of code were determined, David A. Wheeler's \fIsloccount\fP
292 .[
293 sloccount website
294 .]
295 was used to measure the amount in a comparable way.
296
297
298 .U2 "Acknowledgments
299 .P
300 To be written at the very end.
301 .P
302 FIXME