docs/master

annotate preface.roff @ 200:c299ed65d015

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