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. The Complete Table of Contents shows the structure in more detail, though it doesn't list sub-subsections.

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 .htm. 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.

README describes the book.
browhelp.htm has tips for browsing the book and explains some common problems.
copying.htm has the GNU public license with rules for use and copying.
roadmap.htm gives new readers a map to lead them through the book.
servers.htm lists the book's mirror servers around the world.
structur.htm is this file.
to-do.htm lists some of the things that Jerry is hoping to do (that he hopes someone might help him do!) to this book.
updates.htm is a detailed list of changes to the book in each of its new versions.
whatsnew.htm is like a high-level summary of updates.htm.

Index files: Two files have, or point to, all the index entries: indx-cgi.htm is designed for searching by the mh-index CGI script; it's built from individual files in the */indexes subdirectories. indx-map.htm points to individual browsable indexes in the book's sections (subdirectories). There's also a srchhelp.htm file for help with index searching. (The file index.htm, and the symbolic link index.html that points to it, aren't index files. They're the book's home page.)
Tables of Contents: Two almost-identical files have complete tables of contents. toc.htm is for people using the non-frames interface to the book, and frm-toc.htm is the same file with TARGET attributes to drive the frames interface.
Frames Files: Besides the frm-toc.htm file, there are three other files for the frames interface. frm-home.htm sets up the frames. frm-help.htm explains how to use the frames. frm-srch.htm is an interface that runs the mh-index-frames script and returns matching entries with TARGET attributes that the user can click on.

Subdirectories

The book has six user-visible subdirectories:

download: This subdirectory has tar- and ZIP-format archives of the whole book, ready to download, for people who don't want to read online. There's also a subdirectory split with copies of individual scripts and library files; the whole thing is also available as a tarball.
exmh: is for the chapters about the exmh interface to MH.
mh: covers MH and nmh.
mh-e: is for the chapters about the mh-e interface to MH. These files are automatically generated and in a different format than other parts of the book.
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 those except mh-e has subdirectories of its own:

*/figs

This subdirectory has Figures and other graphics.

*/indexes

This subdirectory has the index files:

The cgi file is merged into the top-level indx-cgi.htm file for searching by the mh-index CGI script. The map.htm file points to individual browseable indexes.
The huge all.htm file is also available in almost 26 separate files: one for each letter of the alphabet (except a few letters that aren't used), one for "symbols" like @ and +, and one named jump.htm that ties these little files together.

Most of these files are generated automatically from a file of index entries named index-raw and a list of section titles index-map by a sort-of-buggy Perl script named index-make.pl.

*/tocs

This subdirectory has tables of contents:

One file, all.htm, has the complete table of contents. A version of that file, frames.htm, has the table of contents that's displayed in the bottom frame of this book's frames interface.
The all.htm file is also split into smaller files, one for each chapter and appendix.
The file jump.htm is a summary table of contents that shows the Parts, Chapters and Appendices; each of its Chapter and Appendix entries is a link to one of the smaller per-chapter files.

Missing (Moved) Parts

Some servers probably won't have all of this book. Two Parts of the book, on mh-e and exmh, are also the basis for documentation of those software packages. Those two Parts probably won't be used often by people who use plain MH. Some sites may have copies of just the mh-e or exmh Parts; those Parts will have links back to a site with the rest of the book. And some sites will have only the other Parts, with links to mh-e and exmh. I hope this tangly mess will be straightened out a little (in a backward-compatible way, of course :) as time goes on.

Making Changes

If you want to make changes to the book, I hope you'll get in touch with me and explain what you're trying to do. I might know of someone else who's already doing the same thing. I can put you in touch with other volunteers who are working on the book and help you get your changes distributed.

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

[This book's Home Page] [Table of Contents]

Last change $Date: 1999/10/10 05:14:05 $

This file first appeared in the updated online edition of the book MH & nmh: Email for Users & Programmers, by Jerry Peek. Copyright © 1997 by Jerry Peek. This file is freely available; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation. For more information, see the file copying.htm.

Suggestions are welcome: Jerry Peek <jpeek@jpeek.com>