B::Terse and B::Xref were missing some documentation.

diff --git a/ext/B/B/Terse.pm b/ext/B/B/Terse.pm
index 562c58a..8e551c5 100644 (file)
--- a/ext/B/B/Terse.pm
+++ b/ext/B/B/Terse.pm
@@ -1,6 +1,6 @@
 package B::Terse;
 
-our $VERSION = '1.05';
+our $VERSION = '1.06';
 
 use strict;
 use B qw(class @specialsv_name);
@@ -78,7 +78,15 @@ B::Terse - Walk Perl syntax tree, printing terse info about ops
 
 =head1 DESCRIPTION
 
-This version of B::Terse is really just a wrapper that calls B::Concise
+This module prints the contents of the parse tree, but without as much
+information as L<B::Debug>.  For comparison, C<print "Hello, world.">
+produced 96 lines of output from B::Debug, but only 6 from B::Terse.
+
+This module is useful for people who are writing their own back end,
+or who are learning about the Perl internals.  It's not useful to the
+average programmer.
+
+This version of B::Terse is really just a wrapper that calls L<B::Concise>
 with the B<-terse> option. It is provided for compatibility with old scripts
 (and habits) but using B::Concise directly is now recommended instead.
 

diff --git a/ext/B/B/Xref.pm b/ext/B/B/Xref.pm
index 64e677c..f3a362c 100644 (file)
--- a/ext/B/B/Xref.pm
+++ b/ext/B/B/Xref.pm
@@ -1,6 +1,6 @@
 package B::Xref;
 
-our $VERSION = '1.02';
+our $VERSION = '1.03';
 
 =head1 NAME
 
@@ -48,6 +48,56 @@ letter "i". Subroutine and method calls are indicated by the character
 "&".  Subroutine definitions are indicated by "s" and format
 definitions by "f".
 
+For instance, here's part of the report from the I<pod2man> program that
+comes with Perl:
+
+  Subroutine clear_noremap
+    Package (lexical)
+      $ready_to_print   i1069, 1079
+    Package main
+      $&                1086
+      $.                1086
+      $0                1086
+      $1                1087
+      $2                1085, 1085
+      $3                1085, 1085
+      $ARGV             1086
+      %HTML_Escapes     1085, 1085
+
+This shows the variables used in the subroutine C<clear_noremap>.  The
+variable C<$ready_to_print> is a my() (lexical) variable,
+B<i>ntroduced (first declared with my()) on line 1069, and used on
+line 1079.  The variable C<$&> from the main package is used on 1086,
+and so on.
+
+A line number may be prefixed by a single letter:
+
+=over 4
+
+=item i
+
+Lexical variable introduced (declared with my()) for the first time.
+
+=item &
+
+Subroutine or method call.
+
+=item s
+
+Subroutine defined.
+
+=item r
+
+Format defined.
+
+=back
+
+The most useful option the cross referencer has is to save the report
+to a separate file.  For instance, to save the report on
+I<myperlprogram> to the file I<report>:
+
+  $ perl -MO=Xref,-oreport myperlprogram
+
 =head1 OPTIONS
 
 Option words are separated by commas (not whitespace) and follow the

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 2b5b4e1..6118cd4 100644 (file)
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -114,7 +114,8 @@ XXX
 L<B> has been upgraded from version 1.30 to version 1.31
 
 The XS code has changed slightly, as it was too tightly coupled to
-the contents of the header F<embedvar.h>
+the contents of the header F<embedvar.h>. Documentation in L<B::Terse>
+and L<B::Xref> has been improved, hence their versions have been increased.
 
 =item *