docs/master: preface.roff annotate

annotate preface.roff @ 185:6f8adf7d190c

style: Extended the system to handle appendices and fixed the page hdrs.

author	markus schnalke <meillo@marmaro.de>
date	Wed, 11 Jul 2012 11:05:22 +0200
parents	eb6eeb10afd5
children	05a243dffaca

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

Mercurial > docs > master

annotate preface.roff @ 185:6f8adf7d190c