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.

diff --git a/docs/README.start-devel b/docs/README.start-devel
new file mode 100644 (file)
index 0000000..192c3ff
--- /dev/null
+++ b/docs/README.start-devel
@@ -0,0 +1,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. 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