Structure of the MH Book

This page is for people who want to understand the book's internal structure -- for instance, people who'll revise or extend the book.

The printed book MH & xmh: Email for Users & Programmers, ISBN 1-56592-093-7, had three major editions and some minor revisions in between. There were seven major Parts: three for MH; one each for xmh, MH-E and exmh; and one with appendices. Each part had several chapters or appendices. Almost every chapter and appendix had more than one section. The Section What's in This Book gives a short summary of each part, chapter and appendix.

Files

To convert the book to HTML, I split it into more than 400 separate files. Each major section of a chapter (for example, Sections 1.1, 1.2, 1.3, etc., of Chapter 1) went into its own file. The idea was to make links between sections work quickly: in most cases, to follow a link, a browser only has to load a few kbytes. Each filename starts with from 1 to 8 characters and ends with .html. These short names can be cryptic, but they make the book compatible with filesystems on old DOS computers and CD-ROMs. (People who have slow or no Internet connections can download the book onto their local hard disks; see the browsing help page for info.)

I designed the HTML files to be reorganized. The filenames are meant to be position-independent: they usually aren't related to the place where a section originally fell in the print book. The only section and chapter numbers are in the Tables of Contents. In fact, the "glue" that holds the zillions of files together is in the Tables of Contents and the previous/next links between the files. As the book is rearranged in the future -- with new sections and chapters -- I hope this structure will help to avoid broken links from peoples' bookmarks and other HTML pages.

If a file ever needs to be completely removed, it should be replaced with a "stub" file that points people to the section(s) which replaced the original file. (The stub files don't need to be listed in the Table of Contents -- though, on second thought, maybe there should be a part of the TOC for "Old Stuff".) That way, people with old links to the file can find their way through the new structure. At least, these stub files should have a link to the Table of Contents. Especially, try to avoid renaming a file or changing its purpose -- that means more links need to be changed.

Top-level Directory

In general, files in the top directory apply to all of the book's sections.

Subdirectories

The book has six user-visible subdirectories:
examples
This directory contains copies of individual scripts and library files; the whole thing is also available as a tarball.
index
contains a file for each letter in the index, plus symbols.
exmh
is for the chapters about the exmh interface to MH.
mh
covers MH and nmh.
overall
has chapters that apply to more than one part of the book: for instance, an overview of MIME.
xmh
is for the chapters about the xmh interface to MH.
Each of the latter directories have a single subdirectory and non-HTML file:
*/figs
This subdirectory has Figures and other graphics.
index-raw
This file is used as input by index-make.pl to generate the index files in index.
There used to be a directory for the MH-E chapters, but MH-E now has a book of its own: The MH-E Manual.

Making Changes

If you want to make changes to the book, please join rand-mh-devel at lists.sourceforge.net, send a note, and explain what you're trying to do. You can contribute initially by submitting patches, or by becoming a developer so that you can check in files yourself.

Oh, and please remember that the book is distributed under the GNU General Public License. Please read the file with information about copying, distributing, and modifying this book.

--Jerry Peek, 22 April 1999
--Bill Wohler, 10 May 2006