text_diff( old, new, [options hashref] )

text_diff binds together html_header, create_diff, and html_footer to create a single document that is the "paragraph diff" of the 2 records.

create_diff ( old, new, [options hashref] )

create_diff creates the actual paragraph diff.

NAME

Text::ParagraphDiff - Visual Difference for paragraphed text.

ABSTRACT

Text::ParagraphDiff finds the difference between two paragraphed text files by word rather than by line, reflows the text together, and then outputs result as xhtml.

SYNOPSIS

    use Text::ParagraphDiff;
    print text_diff('old.txt','new.txt');  # old.txt and new.txt are filenames
    print text_diff(\@old,\@new);          # Or pass array references
    print text_diff(["old"], ["new"]);     # T-Diff 2 plain strings (a FAQ)
    print text_diff($old,$new,{plain=>1}); # Pass options (see below)
    # or use the premade script in bin/:
    # ./tdiff oldfile newfile

DESCRIPTION

Text::ParagraphDiff is a reimplementation of diff that is meant for paragraphed text rather than for code. Instead of "diffing" a document by line, Text::ParagraphDiff expands a document to one word per line, uses Algorithm::Diff to find the difference, and then reflows the text back together, highlighting the "add" and "subtract" sections. Writers and editors might find this useful for sending revisions to each other across the internet; a single user might use it to keep track of personal work. For example output, please see diff.html in the distribution, as well as the sources for the difference, old.txt and new.txt.

The output is in xhtml, for ease of generation, ease of access, and ease of viewing. Text::ParagraphDiff also takes advantage of two advanced features of the median: CSS and JavaScript.

CSS is used to cut down on output size and to make the output very pleasing to the eye. JavaScript is used to implement additional functionality: two buttons that can toggle the display of the difference. CSS and JavaScript can be turned off; see the plain option below. (Note: CSS & Javascript tested with ozilla 1.0 and IE 5.x)

OPTIONS

Options are stored in a hashref, $opt. $opt is an optional last argument to text_diff, passed like this:

    text_diff($old, $new, { plain => 1,
                            escape => 1,
                            functionality => 1,
                            style => 'stylesheet_code_here',
                            header => 'header_markup_here'
                          });

Options are:

plain
When set to a true value, plain will cause a document to be rendered plainly, with very sparse html that should be valid even through Netscape Navigator 2.0.
functionality
When set to a true value, functionality will cause the JavaScript toggle buttons to not be shown.
style
When style is set, its value will override the default stylesheet. Please see output_html_header above for the default stylesheet specifications.
header
When header is set, its value will override the default difference header. Please see output_html_header above for more details.
header
When header is set, its value will override the default difference header. Please see output_html_header above for more details.
escape
When escape is set, then output will not be escaped. Useful if you want to include your own markup.
sep
When sep is set, its value will override the default paragraph separator. sep should be a reference to an array of 2 elements; the starting paragraph separator, and the ending separator. The default value is ['<p',</p>']>.
minus_first
By default, when there is a +/- pair, + items appear first by default. However, if minus_first is set to a true value, then the order will be reversed.

EXPORT

text_diff is exported by default. Additionally, create_diff, html_header, and html_footer are optionally exported by request (e.g. use Text::ParagraphDiff qw(create_diff)). create_diff is the actual diff itself; html_header and html_footer should be obvious.

BUGS

In some situations, deletion of entire paragraphs in special places might make the surrounding line-breaks become whacky. If you can isolate the case, please send me a bug report, I might be able to fix it. In the mean time, if this happens to you, just fix the output's markup by hand, it shouldn't be too complicated.

AUTHOR

Joseph F. Ryan (ryan.311@osu.edu) Tests done by Jonas Liljegren (jonas@liljegren.org)

SEE ALSO

Algorithm::Diff.