meillo@0: .H0 "Preface" no
meillo@0: 
meillo@23: .P
meillo@171: I have discovered the mail client \fInmh\fP in fall 2009.
meillo@87: At that time I used \fImutt\fP, as many advanced Unix users do.
meillo@87: When I read about nmh, its concepts convinced me at once.
meillo@87: The transition from mutt to nmh was similar to beginning with
meillo@87: file management in the Unix shell when being used to the
meillo@53: \fImidnight commander\fP,
meillo@87: or like starting with vi when being used to modeless editors.
meillo@87: Such a change is not trivial, but, in being convinced by the
meillo@31: concepts and by having done similar transitions for file management
meillo@53: and editing already, it was not too difficult.
meillo@51: In contrast, setting up nmh to a convenient state became a tedious task
meillo@23: that took several months.
meillo@164: Once having nmh arranged this way, I enjoyed using it
meillo@28: because of its conceptional elegance and its scripting capabilities.
meillo@106: Nevertheless, it was still inconvenient for handling attachments,
meillo@87: non-ASCII character encodings, and similar features of modern emailing.
meillo@31: My setup demanded more and more additional configuration and helper scripts
meillo@87: to have nmh behave the way I wanted; yet my
meillo@31: expectations were rather common for modern emailing.
meillo@106: As a computer scientist and programmer, I wanted to improve the situation.
meillo@8: .P
meillo@171: In spring 2010, I sent a message to the \fInmh-workers\fP mailing list,
meillo@106: asking for the possibility to offer a Google Summer of Code project for me.
meillo@106: Participating in the development of nmh in this manner appeared attractive
meillo@106: to me, because I would have been able to work full time on nmh.
meillo@106: Although the nmh community had reacted generally positive to the suggestion,
meillo@171: the administrative work for such a project would had been too much.
meillo@106: Nonetheless, my proposal had activated the nmh community.
meillo@31: In the following weeks, goals for nmh's future were discussed.
meillo@31: In these discussions, I became involved in the
meillo@53: question whether nmh should include mail transfer facilities.
meillo@34: .[
meillo@34: nmh-workers thread mta mua
meillo@34: .]
meillo@87: I argued for the MTA of nmh to be removed.
meillo@87: In this fundamental question,
meillo@87: my opinion differed from the opinion of most others.
meillo@87: Sadly, besides the discussions, hardly any real work was done.
meillo@87: Being unable to work on nmh in a way that would be accepted at university
meillo@87: as part of my studies, I needed to choose another project.
meillo@8: .P
meillo@23: Half a year later, starting in August 2010,
meillo@23: I took one semester off to travel through Latin America.
meillo@173: During my time in Argentina, I wanted to work on free software.
meillo@23: This brought me back to nmh.
meillo@159: Richard Sandelman, an active nmh user, took care of the official basis.
meillo@173: Juan Granda, an Argentine free software developer,
meillo@87: provided a computer with Internet connection.
meillo@53: Thanks to them, I was able to work on nmh during my three-month
meillo@87: stay in Santiago del Estero, Argentina.
meillo@106: Quickly it became obvious that I would not succeed with my main goal,
meillo@87: to improve the character encoding handling.
meillo@87: (One of its ramifications is the
meillo@87: missing transfer decoding of quoted text in replies.)
meillo@23: As this is one of the most intricate parts of the system, the goal
meillo@53: was simply set too high.
meillo@53: Instead, I improved the code base as I read through it.
meillo@87: I found minor bugs for which I proposed fixes.
meillo@171: Additionally, I improved the documentation in minor ways.
meillo@53: When I started with larger code changes,
meillo@53: I had to discover that the community was reluctant to change.
meillo@53: Its wish for compatibility was much stronger than its
meillo@31: wish for convenient out-of-the-box setups \(en in contrast to my opinion.
meillo@106: This, once again, led to long discussions.
meillo@53: I came to understand their point of view, but it was different to mine.
meillo@23: At the end of my three-month project, I had become familiar with
meillo@87: nmh's code base and community,
meillo@53: I had improved the project in minor ways,
meillo@87: and I still was convinced that I wanted to continue to do so.
meillo@23: .P
meillo@53: Another half year later, the end of my studies came within reach.
meillo@23: I needed a topic for my master's thesis.
meillo@106: Without question, I wanted to work on nmh.
meillo@106: But not exactly on nmh, because I had accepted that its
meillo@106: community has different goals than I have.
meillo@87: Working on nmh would result in much discussion and, in consequence,
meillo@87: little progress.
meillo@23: After careful thought, I decided to start an experimental version of nmh.
meillo@31: I wanted to implement my own ideas of how an MH-like system should look like.
meillo@31: I wanted to create a usable alternative version to be compared with
meillo@31: the present state of nmh.
meillo@53: Eventually, my work would be proven successful or not.
meillo@53: In any case, the nmh project would profit from my experiences.
meillo@28: 
meillo@30: .U2 "Focus of this Document
meillo@8: .P
meillo@53: This document explains the design goals and implementation decisions
meillo@53: for mmh.
meillo@171: .\" XXX mmh taucht hier zum ersten mal auf.
meillo@31: It discusses technical, historical, social and philosophical considerations.
meillo@31: On the technical side, this document
meillo@125: explains how an existing project was streamlined by removing rough edges
meillo@106: and better exploitation of the central concepts.
meillo@106: On the historical side, changes through time are discussed,
meillo@106: regarding the use cases and the email features,
meillo@106: as well as the reactions to them.
meillo@31: Socially, this document describes the effects
meillo@28: and experiences of a newcomer with revolutionary aims entering an old
meillo@53: and matured software project.
meillo@106: Philosophical thoughts on style, mainly based on the Unix
meillo@53: philosophy, are present throughout the discussions.
meillo@53: The document describes the changes to nmh,
meillo@53: but as well, it clarifies my personal perception of the
meillo@53: concepts of MH and Unix, and explain my therefrom resulting point of view.
meillo@23: .P
meillo@31: This document is written for the community around MH-like mail systems,
meillo@31: including developers and users.
meillo@106: Despite the focus on MH-like systems, this document may be valuable
meillo@106: to anyone interested in the Unix philosophy and anyone in contact with
meillo@106: old software projects, be it code- or community-related.
meillo@28: .P
meillo@106: The reader is expected to be familiar with Unix, C and emailing.
meillo@53: Good Unix shell knowledge is required, because MH relies fundamentally
meillo@125: on the shell. Without the power of the shell, MH becomes a motorcycle
meillo@30: without winding roads: boring.
meillo@181: Introductions to Unix and its shell can be found in \fIThe UNIX Programming
meillo@181: Environment\fP by Kernighan and Pike
meillo@37: .[
meillo@37: kernighan pike unix prog env
meillo@37: .]
meillo@181: or \fIThe UNIX System\fP by Bourne.
meillo@37: .[
meillo@37: bourne unix system
meillo@37: .]
meillo@53: The reader is assumed to be a C programmer,
meillo@53: but the document should be understandable otherwise, too.
meillo@53: The definitive guide to C is Kernighan and Ritchie's
meillo@181: \fIThe C Programming Language\fP.
meillo@37: .[
meillo@37: kernighan ritchie c prog lang
meillo@37: .]
meillo@164: A book about system-level C programming, such as those written by
meillo@164: Rochkind and Curry,
meillo@37: .[
meillo@37: rochkind advanced unix prog
meillo@37: .]
meillo@37: .[
meillo@37: curry system prog
meillo@37: .]
meillo@164: can be helpful as additional literature.
meillo@106: Old books are likely more helpful for understanding,
meillo@106: because large parts of the source code are old.
meillo@53: The reader is expected to know the format of email messages and
meillo@53: the structure of email transfer systems, at least on a basic level.
meillo@53: It's advisable to have cross-read the RFCs 821 and 822.
meillo@181: Furthermore, basic understanding of MIME is good to have.
meillo@106: The Wikipedia provides good introduction-level information about email.
meillo@53: .P
meillo@28: Frequent references to the Unix philosophy will be made.
meillo@53: Gancarz has tried to sum it up in his book
meillo@181: \fIThe UNIX Philosophy\fP.
meillo@34: .[
meillo@34: gancarz unix phil
meillo@34: .]
meillo@181: Even better, though less concrete, are \fIThe UNIX Programming
meillo@181: Environment\fP
meillo@34: .[
meillo@34: kernighan pike unix prog env
meillo@34: .]
meillo@181: and \fIThe Practice of Programming\fP
meillo@34: .[
meillo@34: kernighan pike practice of prog
meillo@34: .]
meillo@34: by Kernighan and Pike.
meillo@181: The term paper \fIWhy the Unix Philosophy still matters\fP
meillo@34: .[
meillo@34: why unix phil still matters schnalke
meillo@34: .]
meillo@34: by myself
meillo@53: provides an overview on the philosophy, including a case study of MH.
meillo@53: .P
meillo@30: Although a brief introduction to MH is provided in Chapter 1, the reader
meillo@53: is encouraged to have a look at the \fIMH Book\fP
meillo@181: \fIMH & nmh: Email for Users & Programmers\fP by Jerry Peek.
meillo@34: .[
meillo@34: peek mh
meillo@34: .]
meillo@53: The current version is available freely on the Internet.
meillo@30: It is the definitive guide to MH and nmh.
meillo@30: .P
meillo@30: This document is neither a user's tutorial to mmh nor an introduction
meillo@53: to any of the topics covered.
meillo@53: The technical discussions are on an advanced level.
meillo@52: Nevertheless, as knowledge of the fundamental concepts is the most valuable
meillo@51: information a user can acquire about some program or software system,
meillo@52: this document may be worth a read for non-developers as well.
meillo@8: 
meillo@8: 
meillo@28: .U2 "Organization
meillo@0: .P
meillo@143: This thesis consists of three chapters.
meillo@143: Chapter 1 introduces into the topic, describing MH and explaining
meillo@143: the background and goals of the mmh project.
meillo@143: Chapter 2 discusses the work done in the project.
meillo@143: It is organized along the three major goals of the project, namely
meillo@143: streamlining, modernizing, and styling.
meillo@164: Not every change is described because that would bore the reader.
meillo@143: Instead, important changes and those standing for a set of similar
meillo@143: changes are described and discussed.
meillo@143: Chapter 3 finishes up by summarizing the achivements and taking
meillo@164: a look into the future of the mmh project.
meillo@28: .P
meillo@143: .I "Italic font
meillo@171: is used to emphasize new terms, and to name software projects and
meillo@171: man pages.
meillo@143: .CW "Constant width font
meillo@143: is used to denote names of programs, files,
meillo@143: functions, command lines, code excrepts, program input and output.
meillo@143: .P
meillo@143: References to man pages are printed as ``\c
meillo@143: .Mp cat (1)''.
meillo@143: In this case it is a reference to the man page of
meillo@143: .Pn cat ,
meillo@143: which is in section one of the Unix manual.
meillo@143: Internet technologies are specified by \fIRequests for Comments\fP (RFCs).
meillo@143: Throughout the document, they are referenced in this way ``RFC\|822''.
meillo@143: A list of relevant RFCs is located at the end of the document.
meillo@143: References to literature are printed in backets, like
meillo@143: .[ ``[
meillo@143: kernighan pike unix programming env
meillo@143: .]]'', within the text.
meillo@143: The full references are collected at the end of the document.
meillo@143: .P
meillo@143: This document describes practical programming work.
meillo@143: The code of mmh is managed by the
meillo@143: .Pn git
meillo@143: version control system.
meillo@143: All code changes were checked in.
meillo@143: In the discussions, references to corresponding code changes are printed
meillo@143: as ``\c
meillo@143: .Ci 1a2b3c4 ''.
meillo@143: The identifier is the seven-letter-prefix of the changeset hash value,
meillo@143: which is considered unique.
meillo@143: A change can be looked up in the repository, on the command line with
meillo@143: .Cl "git show XXX" ,
meillo@143: replacing `\f(CWXXX\fP' with the concrete hash value or any unique prefix.
meillo@68: In this example:
meillo@143: .Cl "git show 1a2b3c4" .
meillo@143: At the time of writing, changesets can be looked up online this way:
meillo@143: .CW "http://git.marmaro.de/?p=mmh;a=commitdiff;h=XXX" .
meillo@146: But as we all know, URIs are always at risk to change.
meillo@24: 
meillo@23: 
meillo@28: .U2 "Acknowledgments
meillo@23: .P
meillo@24: To be written at the very end.
meillo@143: .P
meillo@143: FIXME