docs/master

annotate preface.roff @ 143:996c4ac500df

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