Update of /cvsroot/mhonarc/mhonarc/MHonArc/doc/resources
In directory subversions:/tmp/cvs-serv19792/doc/resources
Modified Files:
charsetconverters.html decodeheads.html definederived.html
textclipfunc.html tfirstpglink.html
Added Files:
defcharset.html textencode.html
Log Message:
* Documentation updates, including explanation of TEXTENCODE
resource.
***** Error reading new file: [Errno 2] No such file or directory: 'defcharset.html'
***** Error reading new file: [Errno 2] No such file or directory: 'textencode.html'
Index: charsetconverters.html
===================================================================
RCS file: /cvsroot/mhonarc/mhonarc/MHonArc/doc/resources/charsetconverters.html,v
retrieving revision 1.21
retrieving revision 1.22
diff -C2 -r1.21 -r1.22
*** charsetconverters.html 18 Dec 2002 05:55:22 -0000 1.21
--- charsetconverters.html 21 Dec 2002 07:26:33 -0000 1.22
***************
*** 20,24 ****
<li><small><a href="#MHonArc::CharEnt"><tt>MHonArc::CharEnt::str2sgml</tt></a></small>
<li><small><a href="#MHonArc::UTF8"><tt>MHonArc::UTF8::str2sgml</tt></a></small>
! <li><small><a href="#iso2022jp"><tt>iso2022jp::str2html</tt></a></small>
</ul>
<li><a href="#default">Default Setting</a>
--- 20,24 ----
<li><small><a href="#MHonArc::CharEnt"><tt>MHonArc::CharEnt::str2sgml</tt></a></small>
<li><small><a href="#MHonArc::UTF8"><tt>MHonArc::UTF8::str2sgml</tt></a></small>
! <li><small><a href="#iso2022jp"><tt>iso_2022_jp::str2html</tt></a></small>
</ul>
<li><a href="#default">Default Setting</a>
***************
*** 75,80 ****
</pre>
! <p>CHARSETCONVERTERS resource is also used by
! <a href="mimefilters.html#m2h_text_plain">m2h_text_plain::filter</a>
for message body text.
</p>
--- 75,80 ----
</pre>
! <p>CHARSETCONVERTERS resource is also used by text-based
! <a href="mimefilters.html">MIMEFILTERS</a>
for message body text.
</p>
***************
*** 143,150 ****
<td><strong style="color: red;">WARNING:</strong></td>
<td width="100%"><p>If the decoded data contains the characters '<', '>',
! and '&', this may conflict with HTML markup. See
! <a href="#examples"><cite>Examples</cite></a> below and
<a href="decodeheads.html">DECODEHEADS</a>
! on how <tt>-decode-</tt> can be used.
</p>
</td>
--- 143,151 ----
<td><strong style="color: red;">WARNING:</strong></td>
<td width="100%"><p>If the decoded data contains the characters '<', '>',
! and '&', this may conflict with HTML markup. <tt>-decode-</tt> should
! only be used if <a href="decodeheads.html">DECODEHEADS</a> is active.
! See <a href="#examples"><cite>Examples</cite></a> below and
<a href="decodeheads.html">DECODEHEADS</a>
! for example uses of <tt>-decode-</tt>.
</p>
</td>
***************
*** 311,330 ****
<dt><strong>Usage</strong></dt>
<dd><pre class="code">
! <b><CharsetConverters></b>
! <var>charset-name</var>; MHonArc::UTF8::str2sgml; MHonArc/UTF8.pm
! <b></CharsetConverters></b></pre>
</dd>
<dt><strong>Description</strong></dt>
<dd><p><tt>MHonArc::UTF8::str2sgml</tt> converts data to
! UTF-8.
</p>
! <p>Typical usages is to have it registered
! for all charsets. For example:
</p>
- <pre class="code">
- <b><CharsetConverters override></b>
- plain; mhonarc::htmlize
- default; MHonArc::UTF8::str2sgml; MHonArc/UTF8.pm
- <b></CharsetConverters></b></pre>
<p>See the
<a href="../rcfileexs/utf-8.mrc.html"><tt>utf-8.mrc</tt></a> example
--- 312,337 ----
<dt><strong>Usage</strong></dt>
<dd><pre class="code">
! <b><CharsetConverters override></b>
! plain; mhonarc::htmlize
! default; MHonArc::UTF8::str2sgml; MHonArc/UTF8.pm
! <b></CharsetConverters></b>
!
! <-- Need to also register UTF-8-aware text clipping function -->
! <<a href="textclipfunc.html">TextClipFunc</a>>
! MHonArc::UTF8::clip; MHonArc/UTF8.pm
! </TextClipFunc>
! </pre>
</dd>
<dt><strong>Description</strong></dt>
<dd><p><tt>MHonArc::UTF8::str2sgml</tt> converts data to
! UTF-8. With HTML specials converted to entity references like
! <a href="#mhonarc::htmlize"><tt>mhonarc::htmlize</tt></a>.
</p>
! <p>Typical usages is to have it registered for all charsets,
! since only one <a href="textclipfunc.html">TEXTCLIPFUNC</a>
! can be specified. Having a mixture of UTF-8 and non-UTF-8 data
! can cause clipping problems in resource variables that specify
! a length specifier.
</p>
<p>See the
<a href="../rcfileexs/utf-8.mrc.html"><tt>utf-8.mrc</tt></a> example
***************
*** 335,358 ****
</dl>
! <h3><a name="iso2022jp"><tt>iso2022jp::str2html</tt></a></h3>
<dl>
<dt><strong>Usage</strong></dt>
<dd><pre class="code">
<b><CharsetConverters></b>
! iso-2022-jp; iso2022jp::str2html; iso2022jp.pl
<b></CharsetConverters></b></pre>
</dd>
<dt><strong>Description</strong></dt>
! <dd><p><tt>iso2022jp::str2html</tt> is designed to work
with <tt>iso-2022-jp</tt> within a Japanese locale.
! <tt>iso2022jp::str2html</tt> preserves the
iso-2022-jp encoding format, but converts HTML specials into
character entity references similiar to
<a href="#mhonarc::htmlize"><tt>mhonarc::htmlize</tt></a>.
</p>
<p>Some Japanese-aware processing tools do not support Unicode
character entity references, like those generated by
<a href="#MHonArc::CharEnt"><tt>MHonArc::CharEnt::str2sgml</tt></a>,
! so the <tt>iso2022jp::str2html</tt> may be prefered over
<a href="#MHonArc::CharEnt"><tt>MHonArc::CharEnt::str2sgml</tt></a> for
handling <tt>iso-2022-jp</tt> data.
--- 342,379 ----
</dl>
! <h3><a name="iso2022jp"><tt>iso_2022_jp::str2html</tt></a></h3>
<dl>
<dt><strong>Usage</strong></dt>
<dd><pre class="code">
<b><CharsetConverters></b>
! iso-2022-jp; iso_2022_jp::str2html; iso2022jp.pl
<b></CharsetConverters></b></pre>
</dd>
<dt><strong>Description</strong></dt>
! <dd><p><tt>iso_2022_jp::str2html</tt> is designed to work
with <tt>iso-2022-jp</tt> within a Japanese locale.
! <tt>iso_2022_jp::str2html</tt> preserves the
iso-2022-jp encoding format, but converts HTML specials into
character entity references similiar to
<a href="#mhonarc::htmlize"><tt>mhonarc::htmlize</tt></a>.
</p>
+ <table class="note" width="100%">
+ <tr valign="baseline">
+ <td><strong>NOTE:</strong></td>
+ <td width="100%"><p>If using <tt>iso_2022_jp::str2html</tt>,
+ you should also use the <tt>iso-2022-jp</tt>
+ <a href="textclipfunc.html">text clipping function</a>:
+ </p>
+ <pre class="code">
+ <<a href="textclipfunc.html">TextClipFunc</a>>
+ iso_2022_jp::clip; iso2022jp.pl
+ </TextClipFunc></pre>
+ </td>
+ </tr>
+ </table>
<p>Some Japanese-aware processing tools do not support Unicode
character entity references, like those generated by
<a href="#MHonArc::CharEnt"><tt>MHonArc::CharEnt::str2sgml</tt></a>,
! so the <tt>iso_2022_jp::str2html</tt> may be prefered over
<a href="#MHonArc::CharEnt"><tt>MHonArc::CharEnt::str2sgml</tt></a> for
handling <tt>iso-2022-jp</tt> data.
***************
*** 496,500 ****
<a href="mimedecoders.html">MIMEDECODERS</a>,
<a href="mimefilters.html">MIMEFILTERS</a>,
! <a href="perlinc.html">PERLINC</a>
</p>
--- 517,523 ----
<a href="mimedecoders.html">MIMEDECODERS</a>,
<a href="mimefilters.html">MIMEFILTERS</a>,
! <a href="perlinc.html">PERLINC</a>,
! <a href="textclipfunc.html">TEXTCLIPFUNC</a>,
! <a href="textencode.html">TEXTENCODE</a>
</p>
Index: decodeheads.html
===================================================================
RCS file: /cvsroot/mhonarc/mhonarc/MHonArc/doc/resources/decodeheads.html,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -r1.12 -r1.13
*** decodeheads.html 10 Dec 2002 04:08:02 -0000 1.12
--- decodeheads.html 21 Dec 2002 07:26:33 -0000 1.13
***************
*** 7,11 ****
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="dbfileperms.html">DBFILEPERMS</a>]</td><td><nobr>[<a href="../resources.html#decodeheads">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="definederived.html">DEFINEDERIVED</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
--- 7,11 ----
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="dbfileperms.html">DBFILEPERMS</a>]</td><td><nobr>[<a href="../resources.html#decodeheads">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="defcharset.html">DEFCHARSET</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
***************
*** 121,125 ****
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="dbfileperms.html">DBFILEPERMS</a>]</td><td><nobr>[<a href="../resources.html#decodeheads">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="definederived.html">DEFINEDERIVED</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
--- 121,125 ----
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="dbfileperms.html">DBFILEPERMS</a>]</td><td><nobr>[<a href="../resources.html#decodeheads">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="defcharset.html">DEFCHARSET</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
Index: definederived.html
===================================================================
RCS file: /cvsroot/mhonarc/mhonarc/MHonArc/doc/resources/definederived.html,v
retrieving revision 1.13
retrieving revision 1.14
diff -C2 -r1.13 -r1.14
*** definederived.html 10 Dec 2002 04:08:02 -0000 1.13
--- definederived.html 21 Dec 2002 07:26:33 -0000 1.14
***************
*** 7,11 ****
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="decodeheads.html">DECODEHEADS</a>]</td><td><nobr>[<a href="../resources.html#definederived">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="definevar.html">DEFINEVAR</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
--- 7,11 ----
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="defcharset.html">DEFCHARSET</a>]</td><td><nobr>[<a href="../resources.html#definederived">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="definevar.html">DEFINEVAR</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
***************
*** 354,358 ****
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="decodeheads.html">DECODEHEADS</a>]</td><td><nobr>[<a href="../resources.html#definederived">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="definevar.html">DEFINEVAR</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
--- 354,358 ----
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="defcharset.html">DEFCHARSET</a>]</td><td><nobr>[<a href="../resources.html#definederived">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="definevar.html">DEFINEVAR</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
Index: textclipfunc.html
===================================================================
RCS file: /cvsroot/mhonarc/mhonarc/MHonArc/doc/resources/textclipfunc.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -r1.4 -r1.5
*** textclipfunc.html 10 Dec 2002 04:08:04 -0000 1.4
--- textclipfunc.html 21 Dec 2002 07:26:33 -0000 1.5
***************
*** 7,11 ****
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="tcontend.html">TCONTEND</a>]</td><td><nobr>[<a href="../resources.html#textclipfunc">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="tfirstpglink.html">TFIRSTPGLINK</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
--- 7,11 ----
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="tcontend.html">TCONTEND</a>]</td><td><nobr>[<a href="../resources.html#textclipfunc">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="textencode.html">TEXTENCODE</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
***************
*** 212,285 ****
<h2><a name="examples">Examples</a></h2>
! <p>The <a href="../rcfileexs/utf-8.mrc.html">Unicode</a> example
! resource file sets TEXTCLIPFUNC to a routine that understands UTF-8
! text.
</p>
! <p>The following is the implementation (as of this writing) of
! MHonArc's default clipping function:
</p>
- <pre>
- sub clip_text {
- my $str = \shift; # Prevent unnecessary copy.
- my $len = shift; # Clip length
- my $is_html = shift; # If entity references should be considered
- my $has_tags = shift; # If html tags should be stripped
-
- if (!$is_html) {
- return substr($$str, 0, $len);
- }
-
- my $text = "";
- my $subtext = "";
- my $html_len = length($$str);
- my($pos, $sublen, $erlen, $real_len);
- my $er_len = 0;
-
- for ( $pos=0, $sublen=$len; $pos < $html_len; ) {
- $subtext = substr($$str, $pos, $sublen);
- $pos += $sublen;
-
- # strip tags
- if ($has_tags) {
- $subtext =~ s/\A[^<]*>//; # clipped tag
- $subtext =~ s/<[^>]*>//g;
- $subtext =~ s/<[^>]*\Z//; # clipped tag
- }
-
- # check for clipped entity reference
- if (($pos < $html_len) && ($subtext =~ /\&[^;]*\Z/)) {
- my $semi = index($$str, ';', $pos);
- if ($semi < 0) {
- # malformed entity reference
- $subtext .= substr($$str, $pos);
- $pos = $html_len;
- } else {
- $subtext .= substr($$str, $pos, $semi-$pos+1)
- if $semi > $pos;
- $pos = $semi+1;
- }
- }
-
- # compute entity reference lengths to determine "real" character
- # count and not raw character count.
- while ($subtext =~ /(\&[^;]+);/g) {
- $er_len += length($1);
- }
-
- $text .= $subtext;
-
- # done if we have enough
- $real_len = length($text)-$er_len;
- if ($real_len >= $len) {
- last;
- }
- $sublen = $len - (length($text)-$er_len);
- }
- $text;
- }
- </pre>
-
<!-- *************************************************************** -->
<hr>
--- 212,225 ----
<h2><a name="examples">Examples</a></h2>
! <p>See <a href="charsetconverters.html">CHARSETCONVERTERS</a> and
! <a href="textencode.html">TEXTENCODE</a> resources for example usages
! of TEXTCLIPFUNC.
</p>
! <p>The <a href="../rcfileexs/utf-8.mrc.html">utf-8.mrc</a> example
! resource file sets TEXTCLIPFUNC to a routine that understands UTF-8
! text.
</p>
<!-- *************************************************************** -->
<hr>
***************
*** 293,296 ****
--- 233,240 ----
<h2><a name="seealso">See Also</a></h2>
+ <p>
+ <a href="charsetconverters.html">CHARSETCONVERTERS</a>,
+ <a href="textencode.html">TEXTENCODE</a>
+ </p>
<p><a href="../rcvars.html"><cite>Resource Variables</cite></a>
</p>
***************
*** 300,304 ****
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="tcontend.html">TCONTEND</a>]</td><td><nobr>[<a href="../resources.html#textclipfunc">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="tfirstpglink.html">TFIRSTPGLINK</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
--- 244,248 ----
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="tcontend.html">TCONTEND</a>]</td><td><nobr>[<a href="../resources.html#textclipfunc">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="textencode.html">TEXTENCODE</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
Index: tfirstpglink.html
===================================================================
RCS file: /cvsroot/mhonarc/mhonarc/MHonArc/doc/resources/tfirstpglink.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -r1.9 -r1.10
*** tfirstpglink.html 10 Dec 2002 04:08:04 -0000 1.9
--- tfirstpglink.html 21 Dec 2002 07:26:33 -0000 1.10
***************
*** 7,11 ****
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="textclipfunc.html">TEXTCLIPFUNC</a>]</td><td><nobr>[<a href="../resources.html#tfirstpglink">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="tfoot.html">TFOOT</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
--- 7,11 ----
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="textencode.html">TEXTENCODE</a>]</td><td><nobr>[<a href="../resources.html#tfirstpglink">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="tfoot.html">TFOOT</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
***************
*** 182,186 ****
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="textclipfunc.html">TEXTCLIPFUNC</a>]</td><td><nobr>[<a href="../resources.html#tfirstpglink">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="tfoot.html">TFOOT</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
--- 182,186 ----
<!--x-rc-nav-->
<table border=0><tr valign="top">
! <td align="left" width="50%">[Prev: <a href="textencode.html">TEXTENCODE</a>]</td><td><nobr>[<a href="../resources.html#tfirstpglink">Resources</a>][<a href="../mhonarc.html">TOC</a>]</nobr></td><td align="right" width="50%">[Next: <a href="tfoot.html">TFOOT</a>]</td></tr></table>
<!--/x-rc-nav-->
<hr>
---------------------------------------------------------------------
To sign-off this list, send email to majordomo(_at_)mhonarc(_dot_)org with the
message text UNSUBSCRIBE MHONARC-DEV