[%#
  # IMPORTANT NOTE
  #   This documentation is generated automatically from source
  #   templates.  Any changes you make here may be lost.
  # 
  #   The 'docsrc' documentation source bundle is available for download
  #   from http://www.template-toolkit.org/docs.html and contains all
  #   the source templates, XML files, scripts, etc., from which the
  #   documentation for the Template Toolkit is built.
-%]
[% META book = 'Modules'
        page = 'Plugin_Autoformat'
%]
[%  WRAPPER toc;
	PROCESS tocitem 
	        title ="SYNOPSIS"
                subs  = [];
	PROCESS tocitem 
	        title ="EXAMPLES"
                subs  = [];
	PROCESS tocitem 
	        title ="DESCRIPTION"
                subs  = [];
	PROCESS tocitem 
	        title ="AUTHORS"
                subs  = [];
	PROCESS tocitem 
	        title ="VERSION"
                subs  = [];
	PROCESS tocitem 
	        title ="COPYRIGHT"
                subs  = [];
	PROCESS tocitem 
	        title ="SEE ALSO"
                subs  = [];
    END
%]
<!-- Pod to HTML conversion by the Template Toolkit version 2 -->
[% WRAPPER section
    title="SYNOPSIS"
-%]<pre>    [% tt_start_tag %] USE autoformat(options) [% tt_end_tag %]</pre>
<pre>    [% tt_start_tag %] autoformat(text, more_text, ..., options) [% tt_end_tag %]</pre>
<pre>    [% tt_start_tag %] FILTER autoformat(options) [% tt_end_tag %]
       a block of text
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
[%- END %]
[% WRAPPER section
    title="EXAMPLES"
-%]<pre>    # define some text for the examples
    [% tt_start_tag %] text = BLOCK [% tt_end_tag %]
       Be not afeard.  The isle is full of noises, sounds and sweet 
       airs that give delight but hurt not.
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
<pre>    # pass options to constructor...
    [% tt_start_tag %] USE autoformat(case =&gt; 'upper') [% tt_end_tag %]
    [% tt_start_tag %] autoformat(text) [% tt_end_tag %]</pre>
<pre>    # and/or pass options to the autoformat subroutine itself
    [% tt_start_tag %] USE autoformat [% tt_end_tag %]
    [% tt_start_tag %] autoformat(text, case =&gt; 'upper') [% tt_end_tag %]
    
    # using the autoformat filter
    [% tt_start_tag %] USE autoformat(left =&gt; 10, right =&gt; 30) [% tt_end_tag %]
    [% tt_start_tag %] FILTER autoformat [% tt_end_tag %]
       Be not afeard.  The isle is full of noises, sounds and sweet 
       airs that give delight but hurt not.
    [% tt_start_tag %] END [% tt_end_tag %]</pre>
<pre>    # another filter example with configuration options
    [% tt_start_tag %] USE autoformat [% tt_end_tag %]
    [% tt_start_tag %] FILTER autoformat(left =&gt; 20) [% tt_end_tag %]
       Be not afeard.  The isle is full of noises, sounds and sweet 
       airs that give delight but hurt not.
    [% tt_start_tag %] END [% tt_end_tag %]
    
    # another FILTER example, defining a 'poetry' filter alias
    [% tt_start_tag %] USE autoformat [% tt_end_tag %]
    [% tt_start_tag %] text FILTER poetry = autoformat(left =&gt; 20, right =&gt; 40) [% tt_end_tag %]</pre>
<pre>    # reuse the 'poetry' filter alias
    [% tt_start_tag %] text FILTER poetry [% tt_end_tag %]</pre>
<pre>    # shorthand form ('|' is an alias for 'FILTER')
    [% tt_start_tag %] text | autoformat [% tt_end_tag %]</pre>
<pre>    # using forms
    [% tt_start_tag %] USE autoformat(form =&gt; '&gt;&gt;&gt;&gt;.&lt;&lt;&lt;', numeric =&gt; 'AllPlaces') [% tt_end_tag %]
    [% tt_start_tag %] autoformat(10, 20.32, 11.35) [% tt_end_tag %]</pre>
[%- END %]
[% WRAPPER section
    title="DESCRIPTION"
-%]<p>
The autoformat plugin is an interface to Damian Conway's Text::Autoformat 
Perl module which provides advanced text wrapping and formatting.  
</p>
<p>
Configuration options may be passed to the plugin constructor via the 
USE directive.
</p>
<pre>    [% tt_start_tag %] USE autoformat(right =&gt; 30) [% tt_end_tag %]</pre>
<p>
The autoformat subroutine can then be called, passing in text items which 
will be wrapped and formatted according to the current configuration.
</p>
<pre>    [% tt_start_tag %] autoformat('The cat sat on the mat') [% tt_end_tag %]</pre>
<p>
Additional configuration items can be passed to the autoformat subroutine
and will be merged with any existing configuration specified via the 
constructor.
</p>
<pre>    [% tt_start_tag %] autoformat(text, left =&gt; 20) [% tt_end_tag %]</pre>
<p>
Configuration options are passed directly to the Text::Autoformat plugin.
At the time of writing, the basic configuration items are:
</p>
<pre>    left	left margin (default: 1)
    right	right margin (default 72)
    justify 	justification as one of 'left', 'right', 'full'
                or 'centre' (default: left)
    case        case conversion as one of 'lower', 'upper',
                'sentence', 'title', or 'highlight' (default: none)
    squeeze 	squeeze whitespace (default: enabled)</pre>
<p>
The plugin also accepts a 'form' item which can be used to define a 
format string.  When a form is defined, the plugin will call the 
underlying form() subroutine in preference to autoformat().
</p>
<pre>    [% tt_start_tag %] USE autoformat(form =&gt; '&gt;&gt;&gt;&gt;.&lt;&lt;') [% tt_end_tag %]
    [% tt_start_tag %] autoformat(123.45, 666, 3.14) [% tt_end_tag %]</pre>
<p>
Additional configuration items relevant to forms can also be specified.
</p>
<pre>    [% tt_start_tag %] USE autoformat(form =&gt; '&gt;&gt;&gt;&gt;.&lt;&lt;', numeric =&gt; 'AllPlaces') [% tt_end_tag %]
    [% tt_start_tag %] autoformat(123.45, 666, 3.14) [% tt_end_tag %]</pre>
<p>
These can also be passed directly to the autoformat subroutine.
</p>
<pre>    [% tt_start_tag %] USE autoformat [% tt_end_tag %]
    [% tt_start_tag %] autoformat( 123.45, 666, 3.14,
		   form    =&gt; '&gt;&gt;&gt;&gt;.&lt;&lt;', 
		   numeric =&gt; 'AllPlaces' )
    [% tt_end_tag %]</pre>
<p>
See [% ttlink('Text::Autoformat') -%] for further details.
</p>
[%- END %]
[% WRAPPER section
    title="AUTHORS"
-%]<p>
Robert McArthur &lt;mcarthur@dstc.edu.au&gt; wrote the original plugin 
code, with some modifications and additions from Andy Wardley 
&lt;abw@kfs.org&gt;.
</p>
<p>
Damian Conway &lt;damian@conway.org&gt; wrote the Text::Autoformat 
module (in his copious spare time :-) which does all the clever stuff.
</p>
[%- END %]
[% WRAPPER section
    title="VERSION"
-%]<p>
2.52, distributed as part of the
Template Toolkit version 2.08, released on 30 July 2002.
</p>
[%- END %]
[% WRAPPER section
    title="COPYRIGHT"
-%]<p>
Copyright (C) 2000 Robert McArthur &amp; Andy Wardley.  All Rights Reserved.
</p>
<p>
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
</p>
[%- END %]
[% WRAPPER section
    title="SEE ALSO"
-%]<p>
[% ttlink('Template::Plugin', 'Template::Plugin') -%], [% ttlink('Text::Autoformat', 'Text::Autoformat') -%]
</p>
[%- END %]