| Text::Autoformat - Automatic and manual text wrapping and reformating formatting |
form subform hyphenatesform formatting algorithmform examplesform consumes stringstag sub
Text::Autoformat - Automatic and manual text wrapping and reformating formatting
This document describes version 1.04 of Text::Autoformat, released December 5, 2000.
# Minimal use: read from STDIN, format to STDOUT...
use Text::Autoformat;
autoformat;
# In-memory formatting...
$formatted = autoformat $rawtext;
# Configuration...
$formatted = autoformat $rawtext, { %options };
# Margins (1..72 by default)...
$formatted = autoformat $rawtext, { left=>8, right=>70 };
# Justification (left by default)...
$formatted = autoformat $rawtext, { justify => 'left' };
$formatted = autoformat $rawtext, { justify => 'right' };
$formatted = autoformat $rawtext, { justify => 'full' };
$formatted = autoformat $rawtext, { justify => 'centre' };
# Filling (does so by default)...
$formatted = autoformat $rawtext, { fill=>0 };
# Squeezing whitespace (does so by default)...
$formatted = autoformat $rawtext, { squeeze=>0 };
# Case conversions...
$formatted = autoformat $rawtext, { case => 'lower' };
$formatted = autoformat $rawtext, { case => 'upper' };
$formatted = autoformat $rawtext, { case => 'sentence' };
$formatted = autoformat $rawtext, { case => 'title' };
$formatted = autoformat $rawtext, { case => 'highlight' };
Perl plaintext formatters just aren't smart enough. Given a typical piece of plaintext in need of formatting:
In comp.lang.perl.misc you wrote:
: > <CN = Clooless Noobie> writes:
: > CN> PERL sux because:
: > CN> * It doesn't have a switch statement and you have to put $
: > CN>signs in front of everything
: > CN> * There are too many OR operators: having |, || and 'or'
: > CN>operators is confusing
: > CN> * VB rools, yeah!!!!!!!!!
: > CN> So anyway, how can I stop reloads on a web page?
: > CN> Email replies only, thanks - I don't read this newsgroup.
: >
: > Begone, sirrah! You are a pathetic, Bill-loving, microcephalic
: > script-infant.
: Sheesh, what's with this group - ask a question, get toasted! And how
: *dare* you accuse me of Ianuphilia!
both the venerable Unix fmt tool and Perl's standard Text::Wrap module produce:
In comp.lang.perl.misc you wrote: : > <CN = Clooless Noobie>
writes: : > CN> PERL sux because: : > CN> * It doesn't
have a switch statement and you have to put $ : > CN>signs in
front of everything : > CN> * There are too many OR
operators: having |, || and 'or' : > CN>operators is confusing
: > CN> * VB rools, yeah!!!!!!!!! : > CN> So anyway, how
can I stop reloads on a web page? : > CN> Email replies only,
thanks - I don't read this newsgroup. : > : > Begone, sirrah!
You are a pathetic, Bill-loving, microcephalic : >
script-infant. : Sheesh, what's with this group - ask a
question, get toasted! And how : *dare* you accuse me of
Ianuphilia!
Other formatting modules -- such as Text::Correct and Text::Format -- provide more control over their output, but produce equally poor results when applied to arbitrary input. They simply don't understand the structural conventions of the text they're reformatting.
The Text::Autoformat module provides a subroutine named autoformat that
wraps text to specified margins. However, autoformat reformats its
input by analysing the text's structure, so it wraps the above example
like so:
In comp.lang.perl.misc you wrote:
: > <CN = Clooless Noobie> writes:
: > CN> PERL sux because:
: > CN> * It doesn't have a switch statement and you
: > CN> have to put $ signs in front of everything
: > CN> * There are too many OR operators: having |, ||
: > CN> and 'or' operators is confusing
: > CN> * VB rools, yeah!!!!!!!!! So anyway, how can I
: > CN> stop reloads on a web page? Email replies
: > CN> only, thanks - I don't read this newsgroup.
: >
: > Begone, sirrah! You are a pathetic, Bill-loving,
: > microcephalic script-infant.
: Sheesh, what's with this group - ask a question, get toasted!
: And how *dare* you accuse me of Ianuphilia!
Note that the various quoting conventions have been observed. In fact,
their structure has been used to determine where some paragraphs begin.
Furthermore autoformat correctly distinguished between the leading
'*' bullets of the nested list (which were outdented) and the leading
emphatic '*' of ``*dare*'' (which was inlined).
The fundamental task of the autoformat subroutine is to identify and
rearrange independent paragraphs in a text. Paragraphs typically consist
of a series of lines containing at least one non-whitespace character,
followed by one or more lines containing only optional whitespace.
This is a more liberal definition than many other formatters
use: most require an empty line to terminate a paragraph. Paragraphs may
also be denoted by bulleting, numbering, or quoting (see the following
sections).
Once a paragraph has been isolated, autoformat fills and re-wraps its
lines according to the margins that are specified in its argument list.
These are placed after the text to be formatted, in a hash reference:
$tidied = autoformat($messy, {left=>20, right=>60});
By default, autoformat uses a left margin of 1 (first column) and a
right margin of 72.
Normally, autoformat only reformats the first paragraph it encounters,
and leaves the remainder of the text unaltered. This behaviour is useful
because it allows a one-liner invoking the subroutine to be mapped
onto a convenient keystroke in a text editor, to provide
one-paragraph-at-a-time reformatting:
% cat .exrc
map f !Gperl -MText::Autoformat -e'autoformat'
(Note that to facilitate such one-liners, if autoformat is called
in a void context without any text data, it takes its text from
STDIN and writes its result to STDOUT).
To enable autoformat to rearrange the entire input text at once, the
all argument is used:
$tidied_all = autoformat($messy, {left=>20, right=>60, all=>1});
Often plaintext will include lists that are either:
* bulleted,
* simply numbered (i.e. 1., 2., 3., etc.), or
* hierarchically numbered (1, 1.1, 1.2, 1.3, 2, 2.1. and so forth).
In such lists, each bulleted item is implicitly a separate paragraph, and is formatted individually, with the appropriate indentation:
* bulleted,
* simply numbered (i.e. 1., 2., 3.,
etc.), or
* hierarchically numbered (1, 1.1,
1.2, 1.3, 2, 2.1. and so forth).
More importantly, if the points are numbered, the numbering is checked and reordered. For example, a list whose points have been rearranged:
2. Analyze problem
3. Design algorithm
1. Code solution
5. Test
4. Ship
would be renumbered automatically by autoformat:
1. Analyze problem
2. Design algorithm
3. Code solution
4. Ship
5. Test
The same reordering would be performed if the ``numbering'' was by letters
(a. b. c. etc.) or Roman numerals (i. ii. iii.) or by
some combination of these (1a. 1b. 2a. 2b. etc.) Handling
disordered lists of letters and Roman numerals presents an interesting
challenge. A list such as:
C. Put cat in box.
D. Close lid.
E. Activate Geiger counter.
should be reordered as A. B. C., whereas:
C. Put cat in box.
D. Close lid.
XLI. Activate Geiger counter.
should be reordered I. II. III.
The autoformat subroutine solves this problem by always interpreting
alphabetic bullets as being letters, unless the full list consists
only of valid Roman numerals, at least one of which is two or
more characters long.
Another case in which contiguous lines may be interpreted as belonging to different paragraphs, is where they are quoted with distinct quoters. For example:
: > CN> So anyway, how can I stop reloads on a web page?
: > CN> Email replies only, thanks - I don't read this newsgroup.
: > Begone, sirrah! You are a pathetic, Bill-loving,
: > microcephalic script-infant.
: Sheesh, what's with this group - ask a question, get toasted!
: And how *dare* you accuse me of Ianuphilia!
autoformat recognizes the various quoting conventions used in this example
and treats it as three paragraphs to be independently reformatted.
Block quotations present a different challenge. A typical formatter would render the following quotation:
"We are all of us in the gutter,
but some of us are looking at the stars"
-- Oscar Wilde
like so:
"We are all of us in the gutter, but some of us are looking at
the stars" -- Oscar Wilde
autoformat recognizes the quotation structure by matching the following regular
expression against the text component of each paragraph:
/ \A(\s*) # leading whitespace for quotation
(["']|``) # opening quotemark
(.*) # quotation
(''|\2) # closing quotemark
\s*?\n # trailing whitespace after quotation
(\1[ ]+) # leading whitespace for attribution
# (must be indented more than quotation)
(--|-) # attribution introducer
([^\n]*?\n) # first attribution line
((\5[^\n]*?$)*) # other attribution lines
# (indented no less than first line)
\s*\Z # optional whitespace to end of paragraph
/xsm
When reformatted (see below), the indentation and the attribution structure will be preserved:
"We are all of us in the gutter, but some of us are looking
at the stars"
-- Oscar Wilde
Note that in the last example, autoformat broke the line at column
68, four characters earlier than it should have. It did so because, if
the full margin width had been used, the formatting would have left the
last two words by themselves on an oddly short last line:
"We are all of us in the gutter, but some of us are looking at
the stars"
This phenomenon is known as ``widowing'' and is heavily frowned upon in
typesetting circles. It looks ugly in plaintext too, so autoformat
avoids it by stealing extra words from earlier lines in a
paragraph, so as to leave enough for a reasonable last line. The heuristic
used is that final lines must be at least 10 characters long (though
this number may be adjusted by passing a widow => minlength
argument to autoformat).
If the last line is too short, the paragraph's right margin is reduced by one column, and the paragraph is reformatted. This process iterates until either the last line exceeds nine characters or the margins have been narrowed by 10% of their original separation. In the latter case, the reformatter gives up and uses its original formatting.
The autoformat subroutine also takes a named argument: {justify
=E<gt> I<type>}, which specifies how each paragraph is to be justified.
The options are: 'left' (the default), 'right', 'centre' (or
'center'), and 'full'. These act on the complete paragraph text
(but not on any quoters before that text). For example, with 'right'
justification:
R3> Now is the Winter of our discontent made
R3> glorious Summer by this son of York. And all
R3> the clouds that lour'd upon our house In the
R3> deep bosom of the ocean buried.
Full justification is interesting in a fixed-width medium like plaintext because it usually results in uneven spacing between words. Typically, formatters provide this by distributing the extra spaces into the first available gaps of each line:
R3> Now is the Winter of our discontent made
R3> glorious Summer by this son of York. And all
R3> the clouds that lour'd upon our house In
R3> the deep bosom of the ocean buried.
This produces a rather jarring visual effect, so autoformat reverses
the strategy and inserts extra spaces at the end of lines:
R3> Now is the Winter of our discontent made
R3> glorious Summer by this son of York. And all
R3> the clouds that lour'd upon our house In
R3> the deep bosom of the ocean buried.
Most readers find this less disconcerting.
Even if explicit centring is not specified, autoformat will attempt
to automatically detect centred paragraphs and preserve their
justification. It does this by examining each line of the paragraph and
asking: ``if this line were part of a centred paragraph, where would the
centre line have been?''
The answer can be determined by adding the length of leading whitespace before the first word, plus half the length of the full set of words on the line. That is, for a single line:
$line =~ /^(\s*)(.*?)(\s*)$/
$centre = length($1)+0.5*length($2);
By making the same estimate for every line, and then comparing the
estimates, it is possible to deduce whether all the lines are centred
with respect to the same axis of symmetry (with an allowance of
&plusminus;1 to cater for the inevitable rounding when the centre
positions of even-length rows were originally computed). If a common
axis of symmetry is detected, autoformat assumes that the lines are
supposed to be centred, and switches to centre-justification mode for
that paragraph.
The autoformat subroutine can also optionally perform case conversions
on the text it processes. The {case => type} argument allows the
user to specify five different conversions:
'upper''lower''sentence'{case => 'sentence'}:
'POVERTY, MISERY, ETC. are the lot of the PhD candidate. alas!'
becomes:
'Poverty, misery, etc. are the lot of the PhD candidate. Alas!'
Note that autoformat is clever enough to recognize that the period after abbreviations such as etc. is not a sentence terminator.
If the argument is specified as 'sentence ' (with one or more trailing
whitespace characters) those characters are used to replace the single space
that appears at the end of the sentence. For example,
autoformat($text, {case=>'sentence '}) would produce:
'Poverty, misery, etc. are the lot of the PhD candidate. Alas!'
'title''sentence' except that the first letter of
every word is capitalized:
'What I Did On My Summer Vacation In Monterey'
'highlight''title' except that trivial words are not
capitalized:
'What I Did on my Summer Vacation in Monterey'
form subThe form() subroutine may be exported from the module.
It takes a series of format (or ``picture'') strings followed by
replacement values, interpolates those values into each picture string,
and returns the result. The effect is similar to the inbuilt perl
format mechanism, although the field specification syntax is
simpler and some of the formatting behaviour is more sophisticated.
A picture string consists of sequences of the following characters:
\| is formatted as '|', not a one
character wide centre-justified block field).
Any substitution value which is undef (either explicitly so, or because it
is missing) is replaced by an empty string.
Note that, unlike the a perl format, form preserves whitespace
(including newlines) unless called with certain options.
The ``squeeze'' option (when specified with a true value) causes any sequence of spaces and/or tabs (but not newlines) in an interpolated string to be replaced with a single space.
The ``fill'' option causes newlines to also be squeezed.
Hence:
$frmt = "# [[[[[[[[[[[[[[[[[[[[[";
$data = "h e\t \tl lo\nworld\t\t\t\t\t";
print form $frmt, $data;
# h e l lo
# world
print form {squeeze=>1}, $frmt, $data;
# h e l lo
# world
print form {fill=>1}, $frmt, $data;
# h e l lo world
print form {squeeze=>1, fill=>1}, $frmt, $data;
# h e l lo world
Whether or not filling or squeezing is in effect, form can also be
directed to trim any extra whitespace from the end of each line it
formats, using the ``trim'' option. If this option is specified with a
true value, every line returned by form will automatically have the
substitution s/[ \t]+$//gm applied to it.
Hence:
print length form "[[[[[[[[[[", "short";
# 11
print length form {trim=>1}, "[[[[[[[[[[", "short";
# 6
If form is called with options, but no template string or data, it resets
it's defaults to the options specified. If called in a void context:
form { squeeze => 1, trim => 1 };
the options become permanent defaults.
However, when called with only options in non-void context, form
resets its defaults to those options and returns an object. The reset
default values persist only until that returned object is destroyed.
Hence to temporarily reset form's defaults within a single subroutine:
sub single {
my $tmp = form { squeeze => 1, trim => 1 };
# do formatting with the obove defaults
} # form's defaults revert to previous values as $tmp object destroyed
form hyphenatesAny line with a block field repeats on subsequent lines until all block fields on that line have consumed all their data. Non-block fields on these lines are replaced by the appropriate number of spaces.
Words are wrapped whole, unless they will not fit into the field at all, in which case they are broken and (by default) hyphenated. Simple hyphenation is used (i.e. break at the N-1th character and insert a '-'), unless a suitable alternative subroutine is specified instead.
Words will not be broken if the break would leave less than 2 characters on the current line. This minimum can be varied by setting the 'minbreak' option to a numeric value indicating the minumum total broken characters (including hyphens) required on the current line. Note that, for very narrow fields, words will still be broken (but unhyphenated). For example:
print form '|', 'split';
would print:
s
p
l
i
t
whilst:
print form {minbreak=>1}, '|', 'split';
would print:
s-
p-
l-
i-
t
Alternative breaking subroutines can be specified using the ``break'' option in a configuration hash. For example:
form { break => \&my_line_breaker }
$format_str,
@data;
form expects any user-defined line-breaking subroutine to take three
arguments (the string to be broken, the maximum permissible length of
the initial section, and the total width of the field being filled).
The hypenate sub must return a list of two strings: the initial
(broken) section of the word, and the remainder of the string
respectively).
For example:
sub tilde_break = sub($$$)
{
(substr($_[0],0,$_[1]-1).'~', substr($_[0],$_[1]-1));
}
form { break => \&tilde_break }
$format_str,
@data;
makes '~' the hyphenation character, whilst:
sub wrap_and_slop = sub($$$)
{
my ($text, $reqlen, $fldlen) = @_;
if ($reqlen==$fldlen) { $text =~ m/\A(\s*\S*)(.*)/s }
else { ("", $text) }
}
form { break => \&wrap_and_slop }
$format_str,
@data;
wraps excessively long words to the next line and ``slops'' them over the right margin if necessary.
The Text::Autoformat package provides three functions to simplify the use
of variant hyphenation schemes. The exportable subroutine
Text::Autoformat::break_wrap generates a reference to a subroutine
implementing the ``wrap-and-slop'' algorithm shown in the last example,
which could therefore be rewritten:
use Text::Autoformat qw( form break_wrap );
form { break => break_wrap }
$format_str,
@data;
The subroutine Text::Autoformat::break_with takes a single string
argument and returns a reference to a sub which hyphenates with that
string. Hence the first of the two examples could be rewritten:
use Text::Autoformat qw( form break_wrap );
form { break => break_with('~') }
$format_str,
@data;
The subroutine Text::Autoformat::break_TeX
returns a reference to a sub which hyphenates using
Jan Pazdziora's TeX::Hyphen module. For example:
use Text::Autoformat qw( form break_wrap );
form { break => break_TeX }
$format_str,
@data;
Note that in the previous examples there is no leading '\&' before
break_wrap, break_with, or break_TeX, since each is being
directly called (and returns a reference to some other suitable
subroutine);
form formatting algorithmThe algorithm form uses is:
1. split the first string in the argument list
into individual format lines and add a terminating
newline (unless one is already present).
2. for each format line...
2.1. determine the number of fields and shift
that many values off the argument list and
into the filling list. If insufficient
arguments are available, generate as many
empty strings as are required.
2.2. generate a text line by filling each field
in the format line with the initial contents
of the corresponding arg in the filling list
(and remove those initial contents from the arg).
2.3. replace any <,>, or ^ fields by an equivalent
number of spaces. Splice out the corresponding
args from the filling list.
2.4. Repeat from step 2.2 until all args in the
filling list are empty.
3. concatenate the text lines generated in step 2
4. repeat from step 1 until the argument list is empty
form examplesAs an example of the use of form, the following:
$count = 1;
$text = "A big long piece of text to be formatted exquisitely";
print form q
{
|||| <<<<<<<<<<
----------------
^^^^ ]]]]]]]]]]\|
=
]]].[[[
}, $count, $text, $count+11, $text, "123 123.4\n123.456789";
produces the following output:
1 A big long
----------------
12 piece of|
text to be|
formatted|
exquisite-|
ly|
=
123.0
123.4
123.456
Picture strings and replacement values can be interleaved in the
traditional format format, but care is needed to ensure that the
correct number of substitution values are provided. For example:
$report = form
'Name Rank Serial Number',
'==== ==== =============',
'<<<<<<<<<<<<< ^^^^ <<<<<<<<<<<<<',
$name, $rank, $serial_number,
''
'Age Sex Description',
'=== === ===========',
'^^^ ^^^ [[[[[[[[[[[',
$age, $sex, $description;
form consumes stringsUnlike format, within form non-block fields do consume the text
they format, so the following:
$text = "a line of text to be formatted over three lines";
print form "<<<<<<<<<<\n <<<<<<<<\n <<<<<<\n",
$text, $text, $text;
produces:
a line of
text to
be fo-
not:
a line of
a line
a line
To achieve the latter effect, convert the variable arguments to independent literals (by double-quoted interpolation):
$text = "a line of text to be formatted over three lines";
print form "<<<<<<<<<<\n <<<<<<<<\n <<<<<<\n",
"$text", "$text", "$text";
Although values passed from variable arguments are progressively consumed
within form, the values of the original variables passed to form
are not altered. Hence:
$text = "a line of text to be formatted over three lines";
print form "<<<<<<<<<<\n <<<<<<<<\n <<<<<<\n",
$text, $text, $text;
print $text, "\n";
will print:
a line of
text to
be fo-
a line of text to be formatted over three lines
To cause form to consume the values of the original variables passed to
it, pass them as references. Thus:
$text = "a line of text to be formatted over three lines";
print form "<<<<<<<<<<\n <<<<<<<<\n <<<<<<\n",
\$text, \$text, \$text;
print $text, "\n";
will print:
a line of
text to
be fo-
rmatted over three lines
Note that, for safety, the ``non-consuming'' behaviour takes precedence,
so if a variable is passed to form both by reference and by value,
its final value will be unchanged.
The ``>>>.<<<'' and ``]]].[[['' field specifiers may be used to format numeric values about a fixed decimal place marker. For example:
print form '(]]]]].[[)', <<EONUMS;
1
1.0
1.001
1.009
123.456
1234567
one two
EONUMS
would print:
( 1.0 )
( 1.0 )
( 1.00)
( 1.01)
( 123.46)
(#####.##)
(?????.??)
(?????.??)
Fractions are rounded to the specified number of places after the decimal, but only significant digits are shown. That's why, in the above example, 1 and 1.0 are formatted as ``1.0'', whilst 1.001 is formatted as ``1.00''.
You can specify that the maximal number of decimal places always be used by giving the configuration option 'numeric' a value that matches /\bAllPlaces\b/i. For example:
print form { numeric => AllPlaces },
'(]]]]].[[)', <<'EONUMS';
1
1.0
EONUMS
would print:
( 1.00)
( 1.00)
Note that although decimal digits are rounded to fit the specified width, the integral part of a number is never modified. If there are not enough places before the decimal place to represent the number, the entire number is replaced with hashes.
If a non-numeric sequence is passed as data for a numeric field, it is formatted as a series of question marks. This querulous behaviour can be changed by giving the configuration option 'numeric' a value that matches /\bSkipNaN\b/i in which case, any invalid numeric data is simply ignored. For example:
print form { numeric => 'SkipNaN' }
'(]]]]].[[)',
<<EONUMS;
1
two three
4
EONUMS
would print:
( 1.0 )
( 4.0 )
If an argument corresponding to a field is an array reference, then form
automatically joins the elements of the array into a single string, separating
each element with a newline character. As a result, a call like this:
@values = qw( 1 10 100 1000 );
print form "(]]]].[[)", \@values;
will print out
( 1.00)
( 10.00)
( 100.00)
(1000.00)
as might be expected.
Note however that arrays must be passed by reference (so that form
knows that the entire array holds data for a single field). If the previous
example had not passed @values by reference:
@values = qw( 1 10 100 1000 );
print form "(]]]].[[)", @values;
the output would have been:
( 1.00)
10
100
1000
This is because @values would have been interpolated into form's
argument list, so only $value[0] would have been used as the data for
the initial format string. The remaining elements of @value would have
been treated as separate format strings, and printed out ``verbatim''.
Note too that, because arrays must be passed using a reference, their
original contents are consumed by form, just like the contents of
scalars passed by reference.
To avoid having an array consumed by form, pass it as an anonymous
array:
print form "(]]]].[[)", [@values];
The form subroutine can also insert headers, footers, and page-feeds
as it formats. These features are controlled by the ``header'', ``footer'',
``pagefeed'', ``pagelen'', and ``pagenum'' options.
The ``pagenum'' option takes a scalar value or a reference to a scalar variable and starts page numbering at that value. If a reference to a scalar variable is specified, the value of that variable is updated as the formatting proceeds, so that the final page number is available in it after formatting. This can be useful for multi-part reports.
The ``pagelen'' option specifies the total number of lines in a page (including headers, footers, and page-feeds).
If the ``header'' option is specified with a string value, that string is used as the header of every page generated. If it is specified as a reference to a subroutine, that subroutine is called at the start of every page and its return value used as the header string. When called, the subroutine is passed the current page number.
Likewise, if the ``footer'' option is specified with a string value, that string is used as the footer of every page generated. If it is specified as a reference to a subroutine, that subroutine is called at the start of every page and its return value used as the footer string. When called, the footer subroutine is passed the current page number. If the option is specified as a hash, it acts as described above for the ``header'' option.
Both the header and footer options can also be specified as hash references. In this case the hash entires for keys ``left'', ``centre'' (or ``center''), and ``right'' specify what is to appear on the left, centre, and right of the header/footer. The entry for the key ``width'' specifies how wide the footer is to be. The ``left'', ``centre'', and ``right'' values may be literal strings, or subroutines (just as a normal header/footer specification may be.) See the second example, below.
The ``pagefeed'' option acts in exactly the same way, to produce a pagefeed which is appended after the footer. But note that the pagefeed is not counted as part of the page length.
All three of these page components are recomputed at the start of each new page, before the page contents are formatted (recomputing the header and footer makes it possible to determine how many lines of data to format so as to adhere to the specified page length).
When the call to form is complete and the data has been fully formatted,
the footer subroutine is called one last time, with an extra argument of 1.
The string returned by this final call is used as the final footer.
So for example, a 60-line per page report, starting at page 7, with appropriate headers and footers might be set up like so:
$page = 7;
form { header => sub { "Page $_[0]\n\n" },
footer => sub { return "" if $_[1];
"-"x50 . "\n" . form ">"x50", "...".($_[0]+1);
},
pagefeed => "\n\n",
pagelen => 60
pagenum => \$page,
},
$template,
@data;
Note the recursive use of form within the ``footer'' option.
Alternatively, to set up headers and footers such that the running head is right justified in the header and the page number is centred in the footer:
form { header => { right => "Running head" },
footer => { centre => sub { "Page $_[0]" } },
pagelen => 60
},
$template,
@data;
tag subThe tag subroutine may be exported from the module.
It takes two arguments: a tag specifier and a text to be
entagged. The tag specifier indicates the indenting of the tag, and of the
text. The sub generates an end-tag (using the usual ``/tag'' variant),
unless an explicit end-tag is provided as the third argument.
The tag specifier consists of the following components (in order):
For example:
$text = "three lines\nof tagged\ntext";
print tag "A HREF=#nextsection", $text;
prints:
<A HREF=#nextsection>three lines
of tagged
text</A>
whereas:
print tag "[-:GRIN>>>\n", $text;
prints:
[-:GRIN>>>:-]
three lines
of tagged
text
[-:/GRIN>>>:-]
and:
print tag "\n\n <BOLD>\n\n ", $text, "<END BOLD>";
prints:
<BOLD>
three lines
of tagged
text
<END BOLD>
(with the indicated spacing fore and aft).
Damian Conway (damian@conway.org)
There are undoubtedly serious bugs lurking somewhere in code this funky :-) Bug reports and other feedback are most welcome.
Copyright (c) 1997-2000, Damian Conway. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the terms of the Perl Artistic License (see http://www.perl.com/perl/misc/Artistic.html)
| Text::Autoformat - Automatic and manual text wrapping and reformating formatting |