NAME

Text::Widont - Suppress typographic widows

SYNOPSIS

use Text::Widont;

        # For a single string...
        my $string = 'Look behind you, a Three-Headed Monkey!';
        print widont($string, nbsp->{html});  # "...a Three-Headed Monkey!"

        # For a number of strings...
        my $strings = [
            'You fight like a dairy farmer.',
            'How appropriate. You fight like a cow.',
        ];
        print join "\n", @{ widont( $strings, nbsp->{html} ) };

Or the object oriented way:

use Text::Widont qw( nbsp );

my $tw = Text::Widont->new( nbsp => nbsp->{html} );

        my $string = "I'm selling these fine leather jackets.";
        print $tw->widont($string);  # "...fine leather jackets."

DESCRIPTION

Collins English Dictionary defines a "widow" in typesetting as:

        A short line at the end of a paragraph, especially one that occurs as the
        top line of a page or column.

For example, in the text...

        How much wood could a woodchuck
        chuck if a woodchuck could chuck
        wood?

...the word "wood" at the end is considered a widow. Using "Text::Widont", that sentence would instead appear as...

        How much wood could a woodchuck
        chuck if a woodchuck could
        chuck wood?

NON-BREAKING SPACE TYPES

"Text::Widont" exports a hash ref, "nbsp", that contains the following representations of a non-breaking space to be used with the widont

function

html

The " " HTML character entity.

html_hex

The " " HTML character entity.

html_dec

The " " HTML character entity.

unicode

Unicode's "No-Break Space" character.

FUNCTIONS
widont( $string, $nbsp )
The "widont" function takes a string and returns a copy with the space between the final two words replaced with the given $nbsp. $string can optionally be a reference to an array of strings to transform. In this case strings will be modified in place as well as a copy returned.

In the absence of an explicit $nbsp, Unicode's No-Break Space character will be used.

METHODS

"Text::Widont" also provides an object oriented interface.

->new( nbsp => $nbsp )
Instantiates a new "Text::Widont" object. "nbsp" is an optional argument that will be used when performing the substitution. It defaults to Unicode's No-Break Space character.

->widont( $string )
Performs the substitution described above, using the object's "nbsp" property and the given string.

DEPENDENCIES

"Text::Widont" requires the following modules:

• Carp

BUGS

Please report any bugs or feature requests to "bug-text-widont at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-Widont>.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Text::Widont

You may also look for information at:

• Text::Widont

  <http://perlprogrammer.co.uk/modules/Text::Widont/>

• AnnoCPAN: Annotated CPAN documentation

  <http://annocpan.org/dist/Text-Widont/>

• RT: CPAN's request tracker

  <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-Widont>

• Search CPAN

  <http://search.cpan.org/dist/Text-Widont/>

AUTHOR

Dave Cardwell <dcardwell@cpan.org>

ACKNOWLEDGEMENTS

I was first introduced to the concept of typesetting widows and how they might be solved programatically by Shaun Inman.

<http://www.shauninman.com/archive/2006/08/22/widont_wordpress_plugin>

COPYRIGHT AND LICENSE

Copyright (c) 2007 Dave Cardwell. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.