Pod typos, pod2man bugs, and miscellaneous installation comments

This patch just changed the old a2p.man page into a pod page.

1 files changed, 156 insertions, 0 deletions

diff --git a/x2p/a2p.pod b/x2p/a2p.pod
new file mode 100644
index 0000000000..3976abab67
--- /dev/null
+++ b/x2p/a2p.pod
@@ -0,0 +1,156 @@
+=head1 NAME
+
+a2p - Awk to Perl translator
+
+=head1 SYNOPSIS
+
+B<a2p [options] filename>
+
+=head1 DESCRIPTION
+
+I<A2p> takes an awk script specified on the command line (or from
+standard input) and produces a comparable I<perl> script on the
+standard output.
+
+=head2 Options
+
+Options include:
+
+=over 5
+
+=item B<-DE<lt>numberE<gt>>
+
+sets debugging flags.
+
+=item B<-FE<lt>characterE<gt>>
+
+tells a2p that this awk script is always invoked with this B<-F>
+switch.
+
+=item B<-nE<lt>fieldlistE<gt>>
+
+specifies the names of the input fields if input does not have to be
+split into an array.  If you were translating an awk script that
+processes the password file, you might say:
+
+	a2p -7 -nlogin.password.uid.gid.gcos.shell.home
+
+Any delimiter can be used to separate the field names.
+
+=item B<-E<lt>numberE<gt>>
+
+causes a2p to assume that input will always have that many fields.
+
+=back
+
+=head2 "Considerations"
+
+A2p cannot do as good a job translating as a human would, but it
+usually does pretty well.  There are some areas where you may want to
+examine the perl script produced and tweak it some.  Here are some of
+them, in no particular order.
+
+There is an awk idiom of putting int() around a string expression to
+force numeric interpretation, even though the argument is always
+integer anyway.  This is generally unneeded in perl, but a2p can't
+tell if the argument is always going to be integer, so it leaves it
+in.  You may wish to remove it.
+
+Perl differentiates numeric comparison from string comparison.  Awk
+has one operator for both that decides at run time which comparison to
+do.  A2p does not try to do a complete job of awk emulation at this
+point.  Instead it guesses which one you want.  It's almost always
+right, but it can be spoofed.  All such guesses are marked with the
+comment "C<#???>".  You should go through and check them.  You might
+want to run at least once with the B<-w> switch to perl, which will
+warn you if you use == where you should have used eq.
+
+Perl does not attempt to emulate the behavior of awk in which
+nonexistent array elements spring into existence simply by being
+referenced.  If somehow you are relying on this mechanism to create
+null entries for a subsequent for...in, they won't be there in perl.
+
+If a2p makes a split line that assigns to a list of variables that
+looks like (Fld1, Fld2, Fld3...) you may want to rerun a2p using the
+B<-n> option mentioned above.  This will let you name the fields
+throughout the script.  If it splits to an array instead, the script
+is probably referring to the number of fields somewhere.
+
+The exit statement in awk doesn't necessarily exit; it goes to the END
+block if there is one.  Awk scripts that do contortions within the END
+block to bypass the block under such circumstances can be simplified
+by removing the conditional in the END block and just exiting directly
+from the perl script.
+
+Perl has two kinds of array, numerically-indexed and associative.  Awk
+arrays are usually translated to associative arrays, but if you happen
+to know that the index is always going to be numeric you could change
+the {...} to [...].  Iteration over an associative array is done using
+the keys() function, but iteration over a numeric array is NOT.  You
+might need to modify any loop that is iterating over the array in
+question.
+
+Awk starts by assuming OFMT has the value %.6g.  Perl starts by
+assuming its equivalent, $#, to have the value %.20g.  You'll want to
+set $# explicitly if you use the default value of OFMT.
+
+Near the top of the line loop will be the split operation that is
+implicit in the awk script.  There are times when you can move this
+down past some conditionals that test the entire record so that the
+split is not done as often.
+
+For aesthetic reasons you may wish to change the array base $[ from 1
+back to perl's default of 0, but remember to change all array
+subscripts AND all substr() and index() operations to match.
+
+Cute comments that say "# Here is a workaround because awk is dumb"
+are passed through unmodified.
+
+Awk scripts are often embedded in a shell script that pipes stuff into
+and out of awk.  Often the shell script wrapper can be incorporated
+into the perl script, since perl can start up pipes into and out of
+itself, and can do other things that awk can't do by itself.
+
+Scripts that refer to the special variables RSTART and RLENGTH can
+often be simplified by referring to the variables $`, $& and $', as
+long as they are within the scope of the pattern match that sets them.
+
+The produced perl script may have subroutines defined to deal with
+awk's semantics regarding getline and print.  Since a2p usually picks
+correctness over efficiency.  it is almost always possible to rewrite
+such code to be more efficient by discarding the semantic sugar.
+
+For efficiency, you may wish to remove the keyword from any return
+statement that is the last statement executed in a subroutine.  A2p
+catches the most common case, but doesn't analyze embedded blocks for
+subtler cases.
+
+ARGV[0] translates to $ARGV0, but ARGV[n] translates to $ARGV[$n].  A
+loop that tries to iterate over ARGV[0] won't find it.
+
+=head1 ENVIRONMENT
+
+A2p uses no environment variables.
+
+=head1 AUTHOR
+
+Larry Wall E<lt>F<lwall@jpl-devvax.Jpl.Nasa.Gov>E<gt>
+
+=head1 FILES
+
+=head1 SEE ALSO
+
+ perl	The perl compiler/interpreter
+ 
+ s2p	sed to perl translator
+
+=head1 DIAGNOSTICS
+
+=head1 BUGS
+
+It would be possible to emulate awk's behavior in selecting string
+versus numeric operations at run time by inspection of the operands,
+but it would be gross and inefficient.  Besides, a2p almost always
+guesses right.
+
+Storage for the awk syntax tree is currently static, and can run out.