#!/bin/ksh

OPATH=$PATH PATH=
FPATH=/usr/local/fbin

my_getopts i= j= k= parstart:= infile:= outfile:= "$@"

[[ $HELP == Y ]] && {
  PATH=$OPATH perldoc $0
  exit 0
}

[[ $DEBUG == Y ]] && set -x
[[ -n $INFILE && -r $INFILE ]] && exec 0< $INFILE
[[ -n $OUTFILE ]] && exec 1>$OUTFILE

while IFS= read -r i; do
  if [[ $i == $(print "$PARSTART") ]]; then
    [[ -n "$j" ]] && k="$j$k"
    j="$i\n"
  else
    j="$j$i\n"
  fi
done

k="$j$k"
print "$k\c"

exit $?

=head1 NAME

revpar - reverse paragraphs

=head1 SYNOPSIS

B<revpar>
  B<parstart:=...>
  [B<infile:=...>]
  [B<outfile:=...>]
  [B<help=y>]
  [B<debug=y>]

=head1 DESCRIPTION

B<revpar> reverse the order of serveral paragraphs with starting line
containing $parstart with shell special character escaped.

B<parstart:=...> is used to match the starting line of the paragraph,
as in [[ $i == $(print "$PARSTART") ]].

B<infile:=...> specifies the input file, standard input is used otherwise.

B<outfile:=...> specifies the output file standard output is used otherwise.

B<help=y> displays man page.

B<debug=y> turn on debug mode.

=head1 EXAMPLES

Suppose file "1.1b" has the following lines:

  # version 1.0
  # * this is the first released 
  #   version.
  # version 1.1
  # * minor modification
  # version 2.0
  # * major update

  ./revpar parstart:="# version *" infile:=1.1b outfile:=2.2b
  or
  ./revpar parstart:="*[01]" infile:=1.1b outfile:=2.2b

will reverse the "paragraphs" and write to the output file 2.2b
which contains:

  # version 2.0
  # * major update
  # version 1.1
  # * minor modification
  # version 1.0
  # * this is the first released 
  #   version.

  ./revpar parstart:="*" infile:=1.1b outfile:=2.2b

will reverse the "lines":

  # * major update
  # version 2.0
  # * minor modification
  # version 1.1
  #   version.
  # * this is the first released 
  # version 1.0

=head1 BUG

The input file needs to fit into memoery.

=head1 SEE ALSO

  perl -e "print reverse <>", tac

=head1 AUTHOR AND COPYRIGHT

Michael Wang <F<xw73@columbia.edu>>.

This is free software. You may copy or redistribute it under the same
terms as Perl itself. 

If you modify it, please send a courtesy copy of the modification to
the current maintainer.