[OpenSPARC-T2-DV] / tools / perl-5.8.0 / doc / MHonArc / faq / indexpgs.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
<HTML>
<HEAD>
<TITLE>MHonArc FAQ: Index Pages</TITLE></HEAD>
<BODY>

<!--X-NavButtons-Start-->
<p align=center>
[<a href="archives.html">Prev</a>][<a href="msgpgs.html">Next</a>][<a href="faq.html">TOC</a>][<a href="http://www.mhonarc.org/">Home</a>]
</p>
<!--X-NavButtons-End-->

<!-- ===================================================================== -->
<hr>
<H2><a name="indexpages">Index Pages</a></H2>

<!--X-TOC-Start-->
<ul>
<li><a href="#idxtypes">What are all the different index types?</a></li>
<li><a href="#additional">Can I have additional indexes beyond the default main and thread index?</a></li>
<li><a href="#multipage">Can I have multi-page indexes?</a></li>
<li><a href="#authorsort">Can I sort messages by author?</a></li>
<li><a href="#otherindexes">How does the OTHERINDEXES resource work?</a></li>
<li><a href="#attachments">Can I include links to message attachments on index pages?</a></li>
</ul>
<!--X-TOC-End-->

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=top><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="idxtypes">What are all the different index types?</a></b></h3>
</td></tr></table>

<p>MHonArc catagorizes indexes into to types:
<b>main</b> and <b>thread</b>.  <b>Main</b> covers indexes
listing messages by the following criteria:
</p>
<ul>
<li>Author
<li>Date
<li>Subject
<li>Message number
</ul>

<p>When the documentation refers to <b>main</b> index,
it refers to the index listing messages by author, date, or
subject.  Therefore, all resources. and resource variables, that
refer to the main index apply to either an author, date, or
subject index.  The type of main index is controled by
the SORT, SUBSORT, AUTHSORT resources.
</p>

<p>By default, MHonArc creates a date index
and a thread index.
Author index support is available only in v2.0 and later.
</p>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=top><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="additional">Can I have additional indexes beyond the default main and thread index?</a></b></h3>
</td></tr></table>

<P>Yes. In version 1.2 (or later), a resource was added called
<strong>OTHERINDEXES</strong>. With this resource, you are able to
define an arbitrary number of indexes you desire. The additional
indexes may be in any format you desire and that is supported
by MHonArc. Refer to the documentation for the usage of
<strong>OTHERINDEXES</strong> (also see
"<a href="#otherindexes">How does the OTHERINDEXES resource work?</a>").
</P>

<dl>
<dt><strong>NOTE</strong></dt>
<dd><p>MHonArc will <strong>NOT</strong> automatically
create links to any indexes created via the OTHERINDEXES resource.
You will need to modify the relevant index and messages resources
to contain the additional links.  See the LISTBEGIN and
THEAD resources.
</p>
</dd>
</dl>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=top><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="multipage">Can I have multi-page indexes?</a></b></h3>
</td></tr></table>

<p>Yes, in v2.0 or later.  Setting the MULTIPG and IDXSIZE will cause
indexes to to be listed across multiple pages with IDXSIZE determine
the number of messages listed per page.
</p>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=top><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="authorsort">Can I sort messages by author?</a></b></h3>
</td></tr></table>

<P>Yes, with v2.0 and later.
</P>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=top><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="otherindexes">How does the OTHERINDEXES resource work?</a></b></h3>
</td></tr></table>

<p>I am going to describe a basic example on how OTHERINDEXES can be used.
</p>
<p>First, lets have the top resource file (call it "top.mrc") that
defines the formatting of the default 2 indexes (a main and
a thread).  Example:
</p>
<pre>*** snip "top.mrc" ***
&lt;MAIN&gt;
&lt;THREAD&gt;
&lt;SORT&gt;
&lt;NOTREVERSE&gt;
&lt;NOREVERSE&gt;
*** snip "top.mrc" ***
</pre>
<p>I may have a bunch of layout stuff, but that is not important
for this discussion.
</p>
<p>The above tells MHonArc to create a date and thread index.
I am explicit with the settings to avoid potential unknown settings
from a default resource file (ie. It is always good to be explicit,
especially when we get to otherindexes).
</p>
<p>Now, I would like to also create subject and author indexes.
In "top.mrc" I would add the following:
</p>
<pre>*** snip "top.mrc" ***
&lt;OTHERINDEXES&gt;
subject.mrc
author.mrc
&lt;/OTHERINDEXES&gt;
*** snip "top.mrc" ***
</pre>
<p>The filenames listed are arbitrary, but it is useful if they
imply their purpose.  Since absolute pathnames were not used,
the files will be looked for in the current working directory,
or in the archive directory.  Since the current working directory
may not be appropriate, it is usually best to put the files in
the archive directory.
</p>
<p>The following now shows the important settings for each file:
</p>
<pre>*** snip "subject.mrc" ***
&lt;MAIN&gt;
&lt;NOTHREAD&gt;
&lt;SUBSORT&gt;
&lt;IDXFNAME&gt;
subject.html
&lt;/IDXFNAME&gt;
&lt;IDXPREFIX&gt;
subject
&lt;/IDXPREFIX&gt;
&lt;NOREVERSE&gt;
*** snip "subject.mrc" ***
</pre>
<pre>*** snip "author.mrc" ***
&lt;MAIN&gt;
&lt;NOTHREAD&gt;
&lt;AUTHSORT&gt;
&lt;IDXFNAME&gt;
author.html
&lt;/IDXFNAME&gt;
&lt;IDXPREFIX&gt;
author
&lt;/IDXPREFIX&gt;
&lt;NOREVERSE&gt;
*** snip "author.mrc" ***
</pre>
<p>Again, notice how I am being explicit.  MHonArc does not reset
resources when reading the otherindexes resource files. with one
<em>exception</em>: THREAD is shut-off.  To avoid overriding the default
index files, I must explicitly redefine IDXFNAME (amd IDXPREFIX
if MULTIPG is active).  If I want different layouts for my
other indexes, I must explicitly define those, or they will
use what was ever set in top.mrc (or the applicable default resource setting(s)
when no explicit setting provided).
</p>
<p><strong>NOTE</strong>:
    Otherindexes resource file only defines a *single* index type: main
    or thread.  If you specify the THREAD, a thread index will be
    created and all MAIN related resources are ignored.  I.e.  THREAD
    overrides MAIN.
</p>
<p><strong>WARNING</strong>:
    Do <b>NOT</b> define OTHERINDEXES in your otherindexes resource files.
    Also, make sure there is no self references.  If you do not heed
    these warnings, you will cause an infinite loop, and/or
    unpredictable results.
</p>
<p>Make sure OTHERINDEXES resource files are present for all
updates to an archive.  Mhonarc only stores settings for the
default indexes, so the resource files are needed each time
for other indexes.
</p>
<p>What I left out in this example is the redefinition of the navigational
based resources.  Since I am adding more indexes, I would have to
redefine resources like TOPLINK, BOTLINKS, LISTBEGIN, THEAD, etc, so
there will be links to the other indexes.
</p>

<!-- ??????????????????????????????????????????????????????????????? -->
<hr noshade size=1>
<table border=0>
<tr valign=top><td><img src="monicon.png" align="bottom" alt=""></td><td>
<h3><b><a name="attachments">Can I include links to message attachments on index pages?</a></b></h3>
</td></tr></table>

<p>Not directly, but a (dirty) work-around maybe possible.
You can modify the
mhexternal.pl filter to write to a file (name based off the message
number) with some HTML markup that creates the HTML attachment list
(mhexternal.pl knows about content-types and other stuff, so it can
make a useful list).  Note, since mhexternal.pl works on a single part
at a time, it needs to create the list via append operations to the
file.  The implementation is similiar to how mhexternal.pl supports
placing attachments into a subdirectory.  Make sure that mhexternal.pl
returns the file as part of the return value so it is automatically
deleted if the message is removed from the archive.
</p>
<p>Then, you define the LITEMPLATE resource to use a server-side include
to include the file as part of the message listing.  I did say
it was dirty, but it should work.
</p>

<!-- ===================================================================== -->
<hr>

<!--X-NavButtons-Start-->
<p align=center>
[<a href="archives.html">Prev</a>][<a href="msgpgs.html">Next</a>][<a href="faq.html">TOC</a>][<a href="http://www.mhonarc.org/">Home</a>]
</p>
<!--X-NavButtons-End-->

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