=head2 Tree Rewriting Methods
+=head3 "de-prepping" HTML
+
+Oftentimes, the HTML to be worked with will have multiple sample rows:
+
+ <OL>
+ <LI>bread
+ <LI>butter
+ <LI>beer
+ <LI>bacon
+ </OL>
+
+But, before you begin to rewrite the HTML with your model data, you typically only want 1 or 2 sample rows.
+
+Thus, you want to "crunch" the multiple sample rows to a specified amount. Hence the C<crunch> method:
+
+ $tree->crunch(look_down => [ '_tag' => 'li' ], leave => 2) ;
+
+The C<leave> argument defaults to 1 if not given. The call above would "crunch" the above 4 sample rows to:
+
+ <OL>
+ <LI>bread
+ <LI>butter
+ </OL>
+
+
=head3 Simplifying calls to HTML::FillInForm
Since HTML::FillInForm gets and returns strings, using HTML::Element instances
my $new_tree = $html_tree->fillinform($data_structure);
+
+
=head3 Mapping a hashref to HTML elements
It is very common to get a hashref of data from some external source - flat file, database, XML, etc.
</span>
+=head2 Tree-Killing Methods
+=head3 $tree->prune
-=head1 SEE ALSO
+This removes any nodes from the tree which consist of nothing or nothing but whitespace.
+See also delete_ignorable_whitespace in L<HTML::Element>.
-=over
+=head2 Loltree Functions
+
+A loltree is an arrayref consisting of arrayrefs which is used by
+C<< new_from__lol >> in L<HTML::Element> to produce HTML trees.
+The CPAN distro L<XML::Element::Tolol> creates such XML trees by parsing XML files,
+analagous to L<XML::Toolkit>. The purpose of the functions in this section is to allow
+you manipulate a loltree programmatically.
+
+These could not be methods because if you bless a loltree, then HTML::Tree will barf.
+
+=head3 HTML::Element::newchild($lol, $parent_label, @newchild)
+
+Given this initial loltree:
+
+ my $initial_lol = [ note => [ shopping => [ item => 'sample' ] ] ];
+
+This code:
-=item * L<HTML::Tree>
+ sub shopping_items {
+ my @shopping_items = map { [ item => _ ] } qw(bread butter beans) ;
+ @shopping_items;
+ }
+
+ my $new_lol = HTML::Element::newnode($initial_lol, item => shopping_items());
+
+ will replace the single sample with a list of shopping items:
+
+
+ [
+ 'note',
+ [
+ 'shopping',
+
+ [
+ 'item',
+ 'bread'
+ ],
+ [
+ 'item',
+ 'butter'
+ ],
+ [
+ 'item',
+ 'beans'
+ ]
+
+ ]
+ ];
+
+Thanks to kcott and the other Perlmonks in this thread:
+http://www.perlmonks.org/?node_id=912416
+
+
+=head1 SEE ALSO
-A perl package for creating and manipulating HTML trees
+=head2 L<HTML::Tree>
-=item * L<HTML::ElementTable>
+A perl package for creating and manipulating HTML trees.
+
+=head2 L<HTML::ElementTable>
An L<HTML::Tree> - based module which allows for manipulation of HTML
trees using cartesian coordinations.
-=item * L<HTML::Seamstress>
+=head2 L<HTML::Seamstress>
An L<HTML::Tree> - based module inspired by
XMLC (L<http://xmlc.enhydra.org>), allowing for dynamic
HTML generation via tree rewriting.
+=head2 Push-style templating systems
+
+A comprehensive cross-language
+L<list of push-style templating systems|http://perlmonks.org/?node_id=674225>.
+
+
=head1 TODO
=over
=cut
-=head1 SEE ALSO
-L<HTML::Seamstress>
-
-=head1 AUTHOR / SOURCE
+=head1 AUTHOR and ACKS
Terrence Brannon, E<lt>tbone@cpan.orgE<gt>
+I appreciate the feedback from M. David Moussa Leo Keita regarding some issues with the
+test suite, namely (1) CRLF leading to test breakage in F<t/crunch.t> and (2) using the
+wrong module in F<t/prune.t> thus not having the right functionality available.
+
Many thanks to BARBIE for his RT bug report.
+Many thanks to perlmonk kcott for his work on array rewriting:
+L<http://www.perlmonks.org/?node_id=912416>.
+It was crucial in the development of newchild.
+
+=head2 Source Repo
+
The source is at L<http://github.com/metaperl/html-element-library/tree/master>
=head1 COPYRIGHT AND LICENSE