use strict;
use warnings;


sub is_literal ($$)
 {
 my ($name, $attrs)= @_;
 return ($name eq 'listing') || ($name eq 'signature');  # simple demo.
 # change this to analyse $name and $attrs to decide whether to treat this literally.
 }

sub escape_out ($)
 {
 my $passage= shift;
 $passage =~ s/&/&/g;
 $passage =~ s/</&lt;/g;
 return "[[[* $passage *]]]";  # [[[]]] to visibly show that the right "bite" was taken.
 }

sub scan ($)
 {
 my @passages;
 my $line= shift;
 # first pass: note what sections need treatment, without actually modifying the string.
 # modifying the string would mess up the "pos" used by the RE's.
 while ($line =~ m/<\s*(\w+)([^>]*)>/g) {
    # for every start tag...
    my $startpos= pos($line);
    my $name= $1;
    if (is_literal ($name, $2)) {
       # if targeted, find the matching end tag using simple pattern (ignoring other stuff).
       # this skips that passage for the continued search of all start tags.
       $line =~ m/<\/$name>/g;
       my $endpos= pos($line);
       unshift @passages, [$startpos, $endpos-(length($name)+3)];
       }
    }
 # second pass: process the sections noted above, from right-to-left so
 # positions don't change.
 foreach my $range (@passages) {
    my ($start, $end)= @$range;
    my $length= $end-$start;
    substr($line, $start, $length)= escape_out (substr($line, $start, $length));
         # is there an easier way to do that without substr'ing twice?
    }
 print $line;
 }

my $testdata= <<'EOF';
   <method name="mainloop">
      <signature virtual="1">int mainloop (ratwin::message::MSG&)</signature>
      <P>This is the canonocal logic of the message pump.  It looks aproximatly 
      like this:</P>
      <listing>
          use & and <things> in here.
          MSG msg;
          while ( GetMessage(msg) ) {
             if (msg.hwnd == 0)  thread_message (msg);
             else {
                if (!pre_translate (msg)) {  // check IsDialog,  TranslateAccelerator
                   if (!translate_key_even(msg))  // Win32 TranslateMessage
                      DispatchMessage(msg); 
                   }
                }
             }
          return (msg.wParam);
      </listing>
      <P>Override this if you need to customize this beyond the point provided 
      for by the virtual functions provided for the individual steps.</P>
   </method>
EOF

scan ($testdata);