From 2679bb7e1305b30e1f0bef4612760b5a858456da Mon Sep 17 00:00:00 2001 From: markus schnalke Date: Wed, 11 Apr 2012 12:22:13 +0200 Subject: [PATCH] Added docs/README.start-devel, which recommends who to start with nmh. I've written this more than a year ago, in pre-mmh times, but my advices are still the same. --- docs/README.start-devel | 122 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 docs/README.start-devel diff --git a/docs/README.start-devel b/docs/README.start-devel new file mode 100644 index 0000000..192c3ff --- /dev/null +++ b/docs/README.start-devel @@ -0,0 +1,122 @@ +How to start developing nmh +=========================== + +markus schnalke +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. Nontheless, I encourage you to interact with the +community. You will learn a lot and you will recieve 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 -- 1.7.10.4