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
|
<!-- $Id: structur.html 600 2006-05-31 22:13:43Z wohler $ -->
<html>
<head>
<meta name="Author" content="Jerry Peek">
<title>Structure of the MH Book: MH & nmh: Email for Users & Programmers</title>
<?$book = '.'?>
<link rel="stylesheet" href="<?=$book?>/mh.css" type="text/css">
</head>
<body>
<?
include "$book/mh.php";
includeHeader('copying.html', 'browhelp.html');
?>
<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.html">What's in This
Book</a> gives a short summary of each part, chapter and appendix.
<h2>Files</h2>
<p>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>.html</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.html">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> contains directions for
installing packages of the book as well as other useful
information for using the book.
<li>
<a href="NEWS"><em>NEWS</em></a> contains a list of changes to
each new version of the book. It's partner
file, <a href="NEWS.html"><em>NEWS.html</em></a> is used to
render it more nicely in a browser, as well as provide the
standard header.
<li>
<a href="browhelp.html"><em>browhelp.html</em></a> has tips for
browsing the book and explains some common problems.
<li>
<a href="copying.html"><em>copying.html</em></a> has the GNU
public license with rules for use and copying.
<li>
<a href="roadmap.html"><em>roadmap.html</em></a> gives new
readers a map to lead them through the book.
<li>
<a href="structur.html"><em>structur.html</em></a> is this file.
<li>
<a href="to-do.html"><em>to-do.html</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="whaboo.html"><em>whaboo.html</em></a>
includes <em>overall/whaboo.html</em>, but changes the next and
previous pointers so that if you click Next you
get <em>NEWS</em> instead of <em>overall/neitthed.html</em>.
</ul>
<h2>Subdirectories</h2>
The book has six user-visible subdirectories:
<dl>
<dt><em>examples</em>
<dd>This directory contains copies of individual scripts and
library files; the whole thing is also available as a
<em>tar</em>ball.
<dt><em>index</em>
<dd>contains a file for each letter in the index, plus symbols.
<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>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 the latter directories have a single subdirectory and
non-HTML file:
<dl>
<dt><em>*/figs</em>
<dd>This subdirectory has Figures and other graphics.
<dt><em>index-raw</em>
<dd>This file is used as input by <em>index-make.pl</em> to
generate the index files in <i>index</i>.
</dl>
There used to be a directory for the MH-E chapters, but MH-E now
has a book of its
own: <a href="http://mh-e.sourceforge.net/manual/"><i>The MH-E
Manual</i></a>.
<h2>Making Changes</h2>
If you want to make changes to the book, please
join <a
href="https://lists.sourceforge.net/lists/listinfo/rand-mh-devel">
<i>rand-mh-devel at lists.sourceforge.net</i></a>, send a note,
and explain what you're trying to do. You can contribute initially
by <a
href="http://sourceforge.net/tracker/?group_id=143658&atid=756145">submitting
patches</a>, or by becoming a developer so that you can check in
files yourself.
<p>
Oh, and please remember that the book is distributed under the GNU
General Public License. Please read the file with
<a href="copying.html">information about copying, distributing,
and modifying this book</a>.
<p>
--Jerry Peek, 22 April 1999<br>
--Bill Wohler, 10 May 2006
<?
includeFooter('$Date: 2006-05-31 15:13:43 -0700 (Wed, 31 May 2006) $',
'Jerry: 1997; Bill: 2006');
?>
</body>
</html>
|
