Debian Codegraph @

doc/faq/indexpgs.html

raw
1 <HTML>
2 <HEAD>
3 <TITLE>MHonArc FAQ: Index Pages</TITLE></HEAD>
4 <link rel="stylesheet" type="text/css" href="../docstyles.css">
5 <BODY>
6
7 <!--X-NavButtons-Start-->
8 <table width="100%"><tr><td align="left"><nobr>[<a href="archives.html">Prev</a>]</nobr></td><td align="center" width="100%">[<a href="faq.html">TOC</a>][<a href="../mhonarc.html">Manual</a>][<a href="http://www.mhonarc.org/">Home</a>]</td><td align="right"><nobr>[<a href="msgpgs.html">Next</a>]</nobr></td></tr></table>
9 </p>
10 <!--X-NavButtons-End-->
11
12 <!-- ===================================================================== -->
13 <hr>
14 <H2><a name="indexpages">Index Pages</a></H2>
15
16 <!--X-TOC-Start-->
17 <ul>
18 <li><a href="#idxtypes">What are all the different index types?</a></li>
19 <li><a href="#additional">Can I have additional indexes beyond the default main and thread index?</a></li>
20 <li><a href="#multipage">Can I have multi-page indexes?</a></li>
21 <li><a href="#authorsort">Can I sort messages by author?</a></li>
22 <li><a href="#otherindexes">How does the OTHERINDEXES resource work?</a></li>
23 <li><a href="#attachments">Can I include links to message attachments on index pages?</a></li>
24 </ul>
25 <!--X-TOC-End-->
26
27 <!-- ??????????????????????????????????????????????????????????????? -->
28 <hr noshade size=1>
29 <table border=0>
30 <tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
31 <h3><b><a name="idxtypes">What are all the different index types?</a></b></h3>
32 </td></tr></table>
33
34 <p>MHonArc catagorizes indexes into to types:
35 <b>main</b> and <b>thread</b>. <b>Main</b> covers indexes
36 listing messages by the following criteria:
37 </p>
38 <ul>
39 <li>Author
40 <li>Date
41 <li>Subject
42 <li>Message number
43 </ul>
44
45 <p>When the documentation refers to <b>main</b> index,
46 it refers to the index listing messages by author, date, or
47 subject. Therefore, all resources. and resource variables, that
48 refer to the main index apply to either an author, date, or
49 subject index. The type of main index is controled by
50 the <a href="../resources/sort.html">SORT</a>,
51 <a href="../resources/subsort.html">SUBSORT</a>, and
52 <a href="../resources/authsort.html">AUTHSORT</a>,
53 resources.
54 </p>
55
56 <p>By default, MHonArc creates a date index
57 and a thread index.
58 Author index support is available only in v2.0 and later.
59 </p>
60
61 <!-- ??????????????????????????????????????????????????????????????? -->
62 <hr noshade size=1>
63 <table border=0>
64 <tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
65 <h3><b><a name="additional">Can I have additional indexes beyond the default main and thread index?</a></b></h3>
66 </td></tr></table>
67
68 <P>Yes. In version 1.2 (or later), a resource was added called
69 <a href="../resources/otherindexes.html">OTHERINDEXES</a>.
70 <a href="../resources/otherindexes.html">OTHERINDEXES</a> allows
71 you to define an arbitrary number of indexes you desire. The additional
72 indexes may be in any format you desire.
73 Refer to the documentation for the usage of
74 <a href="../resources/otherindexes.html">OTHERINDEXES</a> (also see
75 "<a href="#otherindexes">How does the OTHERINDEXES resource work?</a>").
76 </P>
77
78 <table class="note" width="100%">
79 <tr valign="baseline">
80 <td><strong>NOTE:</strong></td>
81 <td width="100%"><p>
82 MHonArc will <strong>NOT</strong> automatically
83 create links to any indexes created via the
84 <a href="../resources/otherindexes.html">OTHERINDEXES</a> resource.
85 You will need to modify the relevant index and messages resources
86 to contain the additional links. See the
87 <a href="../resources/listbegin.html">LISTBEGIN</a> and
88 <a href="../resources/thead.html">THEAD</a> resources.
89 </p>
90 </td>
91 </tr>
92 </table>
93
94 <!-- ??????????????????????????????????????????????????????????????? -->
95 <hr noshade size=1>
96 <table border=0>
97 <tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
98 <h3><b><a name="multipage">Can I have multi-page indexes?</a></b></h3>
99 </td></tr></table>
100
101 <p>Yes, in v2.0 or later. Setting the
102 <a href="../resources/multipg.html">MULTIPG</a> and
103 <a href="../resources/idxsize.html">IDXSIZE</a> will cause
104 indexes to to be listed across multiple pages with
105 <a href="../resources/idxsize.html">IDXSIZE</a> determine
106 the number of messages listed per page.
107 </p>
108
109 <!-- ??????????????????????????????????????????????????????????????? -->
110 <hr noshade size=1>
111 <table border=0>
112 <tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
113 <h3><b><a name="authorsort">Can I sort messages by author?</a></b></h3>
114 </td></tr></table>
115
116 <P>Yes, with v2.0 and later.
117 </P>
118
119 <!-- ??????????????????????????????????????????????????????????????? -->
120 <hr noshade size=1>
121 <table border=0>
122 <tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
123 <h3><b><a name="otherindexes">How does the OTHERINDEXES resource work?</a></b></h3>
124 </td></tr></table>
125
126 <p>I am going to describe a basic example on how <a href="../resources/otherindexes.html">OTHERINDEXES</a> can be used.
127 </p>
128 <p>First, lets have the top resource file (call it "top.mrc") that
129 defines the formatting of the default 2 indexes (a main and
130 a thread). Example:
131 </p>
132 <pre class="code">*** snip "top.mrc" ***
133 &lt;<a href="../resources/main.html">MAIN</a>&gt;
134 &lt;<a href="../resources/thread.html">THREAD</a>&gt;
135 &lt;<a href="../resources/sort.html">SORT</a>&gt;
136 &lt;<a href="../resources/treverse.html">NOTREVERSE</a>&gt;
137 &lt;<a href="../resources/reverse.html">NOREVERSE</a>&gt;
138 *** snip "top.mrc" ***
139 </pre>
140 <p>I may have a bunch of layout stuff, but that is not important
141 for this discussion.
142 </p>
143 <p>The above tells MHonArc to create a date and thread index.
144 I am explicit with the settings to avoid potential unknown settings
145 from a default resource file (ie. It is always good to be explicit,
146 especially when we get to otherindexes).
147 </p>
148 <p>Now, I would like to also create subject and author indexes.
149 In "top.mrc" I would add the following:
150 </p>
151 <pre class="code">*** snip "top.mrc" ***
152 &lt;<a href="../resources/otherindexes.html">OTHERINDEXES</a>&gt;
153 subject.mrc
154 author.mrc
155 &lt;/OTHERINDEXES&gt;
156 *** snip "top.mrc" ***
157 </pre>
158 <p>The filenames listed are arbitrary, but it is useful if they
159 imply their purpose. Since absolute pathnames were not used,
160 the files will be looked for in the current working directory,
161 or in the archive directory. Since the current working directory
162 may not be appropriate, it is usually best to put the files in
163 the archive directory.
164 </p>
165 <p>The following now shows the important settings for each file:
166 </p>
167 <pre class="code">*** snip "subject.mrc" ***
168 &lt;<a href="../resources/main.html">MAIN</a>&gt;
169 &lt;<a href="../resources/thread.html">NOTHREAD</a>&gt;
170 &lt;<a href="../resources/subsort.html">SUBSORT</a>&gt;
171 &lt;<a href="../resources/idxfname.html">IDXFNAME</a>&gt;
172 subject.html
173 &lt;/IDXFNAME&gt;
174 &lt;<a href="../resources/idxprefix.html">IDXPREFIX</a>&gt;
175 subject
176 &lt;/IDXPREFIX&gt;
177 &lt;<a href="../resources/reverse.html">NOREVERSE</a>&gt;
178 *** snip "subject.mrc" ***
179 </pre>
180 <pre class="code">*** snip "author.mrc" ***
181 &lt;<a href="../resources/main.html">MAIN</a>&gt;
182 &lt;<a href="../resources/thread.html">NOTHREAD</a>&gt;
183 &lt;AUTHSORT&gt;
184 &lt;<a href="../resources/idxfname.html">IDXFNAME</a>&gt;
185 author.html
186 &lt;/IDXFNAME&gt;
187 &lt;<a href="../resources/idxprefix.html">IDXPREFIX</a>&gt;
188 author
189 &lt;/IDXPREFIX&gt;
190 &lt;<a href="../resources/reverse.html">NOREVERSE</a>&gt;
191 *** snip "author.mrc" ***
192 </pre>
193 <p>Again, notice how I am being explicit. MHonArc does not reset
194 resources when reading the otherindexes resource files. with one
195 <em>exception</em>: <a href="../resources/thread.html">THREAD</a> is shut-off. To avoid overriding the default
196 index files, I must explicitly redefine <a href="../resources/idxfname.html">IDXFNAME</a> (and <a href="../resources/idxprefix.html">IDXPREFIX</a>
197 if <a href="../resources/multipg.html">MULTIPG</a> is active). If I want different layouts for my
198 other indexes, I must explicitly define those, or they will
199 use what was ever set in top.mrc (or the applicable default resource setting(s)
200 when no explicit setting provided).
201 </p>
202 <table class="note" width="100%">
203 <tr valign="baseline">
204 <td><strong>NOTE:</strong></td>
205 <td width="100%"><p>
206 Otherindexes resource file only defines a <strong>single</strong>
207 index type: main or thread. If you specify the
208 <a href="../resources/thread.html">THREAD</a>, a thread index will be
209 created and all <a href="../resources/main.html">MAIN</a> related resources are ignored.
210 </p>
211 </td>
212 </tr>
213 </table>
214 <p> </p>
215 <table class="caution" width="100%">
216 <tr valign="baseline">
217 <td><strong style="color: red;">WARNING:</strong></td>
218 <td width="100%"><p>
219 Do <b>NOT</b> define <a href="../resources/otherindexes.html">OTHERINDEXES</a> in your otherindexes resource files.
220 Also, make sure there is no self references. If you do not heed
221 these warnings, you will cause an infinite loop, and/or
222 unpredictable results.
223 </p>
224 </td>
225 </tr>
226 </table>
227 <p>Make sure <a href="../resources/otherindexes.html">OTHERINDEXES</a> resource files are present for all
228 updates to an archive. Mhonarc only stores settings for the
229 default indexes, so the resource files are needed each time
230 for other indexes.
231 </p>
232
233 <p>What is left out of this example is the redefinition
234 of navigational based resources. Since I am adding
235 more indexes, I would have to redefine resources like
236 <a href="../resources/toplinks.html">TOPLINKS</a>,
237 <a href="../resources/botlinks.html">BOTLINKS</a>,
238 <a href="../resources/listbegin.html">LISTBEGIN</a>,
239 <a href="../resources/thead.html">THEAD</a>, etc, so there will be links
240 to the other indexes.
241 </p>
242
243 <!-- ??????????????????????????????????????????????????????????????? -->
244 <hr noshade size=1>
245 <table border=0>
246 <tr valign=baseline><td><img src="monicon.png" align="bottom" alt=""></td><td>
247 <h3><b><a name="attachments">Can I include links to message attachments on index pages?</a></b></h3>
248 </td></tr></table>
249
250 <p>Not directly, but a (dirty) work-around maybe possible.
251 You can modify the
252 mhexternal.pl filter to write to a file (name based off the message
253 number) with some HTML markup that creates the HTML attachment list
254 (mhexternal.pl knows about content-types and other stuff, so it can
255 make a useful list). Note, since mhexternal.pl works on a single part
256 at a time, it needs to create the list via append operations to the
257 file. The implementation is similiar to how mhexternal.pl supports
258 placing attachments into a subdirectory. Make sure that mhexternal.pl
259 returns the file as part of the return value so it is automatically
260 deleted if the message is removed from the archive.
261 </p>
262 <p>Then, you define the <a href="../resources/litemplate.html">LITEMPLATE</a>
263 resource to use a server-side include
264 to include the file as part of the message listing. I did say
265 it was dirty, but it should work.
266 </p>
267
268 <!-- ===================================================================== -->
269 <hr>
270
271 <!--X-NavButtons-Start-->
272 <table width="100%"><tr><td align="left"><nobr>[<a href="archives.html">Prev</a>]</nobr></td><td align="center" width="100%">[<a href="faq.html">TOC</a>][<a href="../mhonarc.html">Manual</a>][<a href="http://www.mhonarc.org/">Home</a>]</td><td align="right"><nobr>[<a href="msgpgs.html">Next</a>]</nobr></td></tr></table>
273 </p>
274 <!--X-NavButtons-End-->
275
276 <HR>
277 <address>
278 $Date: 2005/05/25 19:51:01 $ <br>
279 <img align="top" src="monicon.png" alt="">
280 <a href="http://www.mhonarc.org/"
281 ><strong>MHonArc</strong></a><br>
282 Copyright &#169; 1997-1999, <a href="http://www.earlhood.com/"
283 >Earl Hood</a>, <a href="mailto:mhonarc&#37;40mhonarc.org"
284 >mhonarc<!--
285 -->&#64;<!--
286 -->mhonarc.org</a><br>
287 </address>
288 </BODY>
289 </HTML>