1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
How to start developing nmh
===========================
markus schnalke <meillo@marmaro.de>
2010-12
I started using nmh in Fall 2009. Soon afterwards, I used it exclusivly.
In Spring 2010, I subscribed to the nmh-workers mailing list. From
October until December 2010, I worked for two month full-time on nmh as
a private project.
First of all, I needed to become familiar with the code. This had been
the most difficult part. This document is based on my experience on
starting to hack nmh. It describes how I would do it a second time.
These are my recommendations.
Prerequisites
-------------
You should be familiar with nmh. Use it!
Adjust nmh to your needs. This is almost a requirement for using it
for modern emailing. It took me several month until I had a satisfying
setup. Lots of research and reading was necessary.
Subscribe to the nmh-workers mailing list [0] and read it.
Reading documentation
---------------------
Read Jerry Peek's book ``MH & nmh: Email for Users & Programmers'' [1],
at least the history, concepts, and get an overview of the rest. This
book is a wonderful resource for everything about nmh.
Cross-read the FAQs [2] although they are old.
Read README and docs/README.developers. The rest below docs/ is
valuable too. You might want to read it now or later.
Reading code
------------
I split the task of code reading into five stages.
(1) Get an overview:
Understand the directory structure. Get a feeling for what kinds of
files are unter sbr/ and what under uip/. Scrolling through the files
is sufficient for that. These two directories will be most important.
See docs/README.developers for help.
(2) Take a look at some simple tool:
I recommend reading uip/rmm.c, which is a pretty straight-forward
tool. It shows the structure of the common tool code in nmh pretty
well. You don't need to fully understand it, but you should try to
find out how things work generally. The identifiers and comments in
the code will provide most of that information.
(3) Read through the header files:
Read h/mh.h, the central header file of the project. It contains a lot
of important information. Like above, you don't need to understand it
fully now. Later, jump back to this header file as needed in order to
incrementally understand it better and better.
(4) Read code in uip/, starting with simple tools:
Now you can continue reading tool code in uip/. Go from the simple
tools (e.g. mhparam, mhpath) to the more complex ones (e.g. send,
pick, spost). Defer everything with MIME involved (e.g. mhshow,
mhbuild) and the tools that use format or component files until the
end. As a rule of thumb: Simple tools are those with few lines of code
and no *sbr.c files.
(5) Jump to sbr/ as needed:
As you read through the code, you'll encounter several functions that
are not part of the C standard library but of similar style. Look for
these below sbr/. There most files are named like the single function
they contain. You can often guess from the filename what is inside.
Read their sources as you need them. I found it useful to write down
short explanations of functions whose names didn't express enough
information.
Once you reached this point, I'm sure you'll find your further way
alone.
Code history
------------
Note that large parts of the code are very old and were written by a
whole bunch of different people. You will likely encounter code that
simply puzzles you. Check the ChangeLog and similar sources first. If
you still don't understand, ask on the mailing list. You'll see that
the folks there sometimes don't know either. A lot of knowledge was
lost in time.
The Community
-------------
A short note for those who come from the modern Free Software world:
Don't expect nmh to be like modern Free Software projects. Nmh is old
and MH is much older. The community still carries old spirits; you
might not be used to them. Also, keep in mind that nmh is matured
back-end software, thus the view on change may be different than you
might expect. Nonetheless, I encourage you to interact with the
community. You will learn a lot and you will receive valuable comments.
REFERENCES
----------
[0] http://lists.nongnu.org/mailman/listinfo/nmh-workers
[1] http://rand-mh.sourceforge.net/book/
[2] http://www.newt.com/faq/mh.html
|
