1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
<HTML>
<HEAD>
<META NAME="Author" CONTENT="Jerry Peek">
<TITLE>Structure of the MH Book</TITLE>
</HEAD>
<!-- $Id: structur.htm,v 6.0 1999/10/10 05:14:05 jpeek Exp $ -->
<BODY BGCOLOR="#FFFFFF">
<H1>Structure of the MH Book</H1>
<P>
This page is for people who want to understand the book's internal structure
-- for instance, people who'll revise or extend the book.
<P>
The printed book <EM>MH & xmh: Email for Users & Programmers</EM>,
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 <EM>xmh</EM>,
mh-e and <EM>exmh</EM>; and one with appendices.
Each part had several chapters or appendices.
Almost every chapter and appendix had more than one section.
The Section <A HREF="overall/whaboo.htm">What's in This Book</A>
gives a short summary of each part, chapter and appendix.
The <A HREF="toc.htm">Complete Table of Contents</A>
shows the structure in more detail, though it doesn't list sub-subsections.
<H2>Files</H2>
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 <EM>.htm</EM>.
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
<A HREF="browhelp.htm">browsing help page</A> for info.)
<P>
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.
<P>
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.
<H2>Top-level Directory</H2>
In general, files in the top directory apply to all of the book's sections.
<UL>
<LI>
<A HREF="README"><EM>README</EM></A> describes the book.
<LI>
<A HREF="browhelp.htm"><EM>browhelp.htm</EM></A> has tips for browsing the
book and explains some common problems.
<LI>
<A HREF="copying.htm"><EM>copying.htm</EM></A> has the GNU public license
with rules for use and copying.
<LI>
<A HREF="roadmap.htm"><EM>roadmap.htm</EM></A> gives new readers a map to
lead them through the book.
<LI>
<A HREF="servers.htm"><EM>servers.htm</EM></A> lists the book's mirror
servers around the world.
<LI>
<A HREF="structur.htm"><EM>structur.htm</EM></A> is this file.
<LI>
<A HREF="to-do.htm"><EM>to-do.htm</EM></A> lists some of the things that
Jerry is hoping to do (that he hopes someone might help him do!) to this book.
<LI>
<A HREF="updates.htm"><EM>updates.htm</EM></A> is a detailed list of changes
to the book in each of its new versions.
<LI>
<A HREF="whatsnew.htm"><EM>whatsnew.htm</EM></A> is like
a high-level summary of <EM>updates.htm</EM>.
</UL>
<DL>
<DT><B>Index files</B>
<DD>Two files have, or point to, all the index entries:
<EM>indx-cgi.htm</EM> is designed for searching by the <EM>mh-index</EM> CGI
script; it's built from individual files in the <EM>*/indexes</EM>
subdirectories.
<EM>indx-map.htm</EM> points to individual browsable indexes in the
book's sections (subdirectories).
There's also a <A HREF="srchhelp.htm"><EM>srchhelp.htm</EM> file</A>
for help with index searching.
(The file <EM>index.htm</EM>, and the symbolic link <EM>index.html</EM> that
points to it, aren't index files.
They're the book's home page.)
<DT><B>Tables of Contents</B>
<DD>Two almost-identical files have complete tables of contents.
<EM>toc.htm</EM> is for people using the non-frames interface to the book,
and <EM>frm-toc.htm</EM> is the same file with TARGET attributes to drive
the frames interface.
<DT><B>Frames Files</B>
<DD>Besides the <EM>frm-toc.htm</EM> file,
there are three other files for the frames interface.
<EM>frm-home.htm</EM> sets up the frames.
<EM>frm-help.htm</EM> explains how to use the frames.
<EM>frm-srch.htm</EM> is an interface that runs the <EM>mh-index-frames</EM>
script and returns matching entries with TARGET attributes that the user
can click on.
</DL>
<H2>Subdirectories</H2>
The book has six user-visible subdirectories:
<DL>
<DT><EM>download</EM>
<DD>This subdirectory has <EM>tar</EM>- 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 <EM>split</EM> with copies of individual
scripts and library files; the whole thing is also available as a
<EM>tar</EM>ball.
<DT><EM>exmh</EM>
<DD>is for the chapters about the <EM>exmh</EM> interface to MH.
<DT><EM>mh</EM>
<DD>covers MH and nmh.
<DT><EM>mh-e</EM>
<DD>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.
<DT><EM>overall</EM>
<DD>has chapters that apply to more than one part of the book:
for instance, an overview of MIME.
<DT><EM>xmh</EM>
<DD>is for the chapters about the <EM>xmh</EM> interface to MH.
</DL>
Each of those except <EM>mh-e</EM> has subdirectories of its own:
<DL>
<DT><EM>*/figs</EM>
<DD>This subdirectory has Figures and other graphics.
<DT><EM>*/indexes</EM>
<DD>This subdirectory has the index files:
<UL>
<LI>
The <EM>cgi</EM> file is merged into the top-level <EM>indx-cgi.htm</EM>
file for searching by the <EM>mh-index</EM> CGI script.
The <EM>map.htm</EM> file points to individual browseable indexes.
<LI>
The huge <EM>all.htm</EM> 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 <TT>@</TT> and <TT>+</TT>,
and one named <EM>jump.htm</EM> that ties these little files together.
</UL>
Most of these files are generated automatically from a file of index entries
named <EM>index-raw</EM> and a list of section titles <EM>index-map</EM>
by a sort-of-buggy Perl script named <EM>index-make.pl</EM>.
<DT><EM>*/tocs</EM>
<DD>This subdirectory has tables of contents:
<UL>
<LI>
One file, <EM>all.htm</EM>, has the complete table of contents.
A version of that file, <EM>frames.htm</EM>, has the table of contents
that's displayed in the bottom frame of this book's frames interface.
<LI>
The <EM>all.htm</EM> file is also split into smaller files, one for each
chapter and appendix.
<LI>
The file <EM>jump.htm</EM> 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.
</UL>
</DL>
<H2>Missing (Moved) Parts</H2>
Some servers probably won't have all of this book.
Two Parts of the book, on mh-e and <EM>exmh</EM>, 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 <EM>exmh</EM> 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
<EM>exmh</EM>.
I hope this tangly mess will be straightened out a little
(in a backward-compatible way, of course :) as time goes on.
<H2>Making Changes</H2>
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.
<P>
Oh, and please remember that the book is distributed under the GNU General
Public License.
Please read the file with
<A HREF="copying.htm">information about copying, distributing, and modifying
this book</A>.
<P>
--Jerry Peek, 22 April 1999
<P ALIGN=CENTER>
[<A HREF="index.htm">This book's Home Page</A>]
[<A HREF="toc-jump.htm">Table of Contents</A>]
<!-- There used to be a link to toc here ... -->
</P>
<HR>
<EM>Last change $Date: 1999/10/10 05:14:05 $</EM>
<P>
This file first appeared in the updated online edition of the book
<EM>MH & nmh: Email for Users & Programmers</EM>, 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
<A HREF="copying.htm">the file <EM>copying.htm</EM></A>.
<P>
<ADDRESS>
Suggestions are welcome:
<A HREF="http://www.jpeek.com/">Jerry Peek</A>
<A HREF="mailto:jpeek@jpeek.com"><jpeek@jpeek.com></A>
</ADDRESS>
</BODY>
</HTML>
|
