File: structur.html

package info (click to toggle)
mh-book 200605-2
  • links: PTS
  • area: main
  • in suites: bullseye, buster, sid, stretch
  • size: 6,356 kB
  • ctags: 2,059
  • sloc: sh: 1,449; perl: 642; ansic: 279; php: 58; makefile: 39; csh: 8
file content (181 lines) | stat: -rw-r--r-- 6,900 bytes parent folder | download | duplicates (2)
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 &amp; 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 &amp; xmh: Email for Users &amp;
    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>