Structure of This 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 (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.

Subdirectories

Most of the files are in a single top-level directory. Wherever I could, though, I split chunks of files into subdirectories.

figs

This subdirectory has Figures and other graphics from the original book.

indexes

This subdirectory has the Index files.

Two files have all the index entries: cgi.htm is designed for searching by the mh-index CGI script, and all.htm is formatted for browsing on its own.
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.
There's also a map.htm file that points to all the other index files, and a srchhelp.htm file for help with index searching.

Most of these files are generated automatically from a file named index-raw and a sort-of-buggy Perl script named index-make.pl. These "hacker's" files won't be in the archive until the script is more stable; if you need to add index entries, please get in touch with me.

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. Those Parts will probably change more quickly than the Parts about MH and xmh. So, 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, 5 June 1996

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

Last change $Date: 1996/06/06 15:14:27 $

This file is from the third edition of the book MH & xmh: Email for Users & Programmers, ISBN 1-56592-093-7, by Jerry Peek. Copyright © 1991, 1992, 1995 by O'Reilly & Associates, Inc. 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>