fate: document TARGET_EXEC and its usage
[ffmpeg.git] / doc / texi2pod.pl
index 6971e6c..94323be 100755 (executable)
@@ -16,8 +16,8 @@
 
 # You should have received a copy of the GNU General Public License
 # along with GNU CC; see the file COPYING.  If not, write to
 
 # You should have received a copy of the GNU General Public License
 # along with GNU CC; see the file COPYING.  If not, write to
-# the Free Software Foundation, 59 Temple Place - Suite 330,
-# Boston MA 02111-1307, USA.
+# the Free Software Foundation, 51 Franklin Street, Fifth Floor,
+# Boston, MA 02110-1301 USA
 
 # This does trivial (and I mean _trivial_) conversion of Texinfo
 # markup to Perl POD format.  It's intended to be used to extract
 
 # This does trivial (and I mean _trivial_) conversion of Texinfo
 # markup to Perl POD format.  It's intended to be used to extract
@@ -26,6 +26,7 @@
 $output = 0;
 $skipping = 0;
 %sects = ();
 $output = 0;
 $skipping = 0;
 %sects = ();
+@sects_sequence = ();
 $section = "";
 @icstack = ();
 @endwstack = ();
 $section = "";
 @icstack = ();
 @endwstack = ();
@@ -35,35 +36,39 @@ $shift = "";
 %defs = ();
 $fnno = 1;
 $inf = "";
 %defs = ();
 $fnno = 1;
 $inf = "";
-$ibase = "";
+@ibase = ();
 
 while ($_ = shift) {
     if (/^-D(.*)$/) {
 
 while ($_ = shift) {
     if (/^-D(.*)$/) {
-       if ($1 ne "") {
-           $flag = $1;
-       } else {
-           $flag = shift;
-       }
-       $value = "";
-       ($flag, $value) = ($flag =~ /^([^=]+)(?:=(.+))?/);
-       die "no flag specified for -D\n"
-           unless $flag ne "";
-       die "flags may only contain letters, digits, hyphens, dashes and underscores\n"
-           unless $flag =~ /^[a-zA-Z0-9_-]+$/;
-       $defs{$flag} = $value;
+        if ($1 ne "") {
+            $flag = $1;
+        } else {
+            $flag = shift;
+        }
+        $value = "";
+        ($flag, $value) = ($flag =~ /^([^=]+)(?:=(.+))?/);
+        die "no flag specified for -D\n"
+            unless $flag ne "";
+        die "flags may only contain letters, digits, hyphens, dashes and underscores\n"
+            unless $flag =~ /^[a-zA-Z0-9_-]+$/;
+        $defs{$flag} = $value;
+    } elsif (/^-I(.*)$/) {
+        push @ibase, $1 ne "" ? $1 : shift;
     } elsif (/^-/) {
     } elsif (/^-/) {
-       usage();
+        usage();
     } else {
     } else {
-       $in = $_, next unless defined $in;
-       $out = $_, next unless defined $out;
-       usage();
+        $in = $_, next unless defined $in;
+        $out = $_, next unless defined $out;
+        usage();
     }
 }
 
     }
 }
 
+push @ibase, ".";
+
 if (defined $in) {
     $inf = gensym();
     open($inf, "<$in") or die "opening \"$in\": $!\n";
 if (defined $in) {
     $inf = gensym();
     open($inf, "<$in") or die "opening \"$in\": $!\n";
-    $ibase = $1 if $in =~ m|^(.+)/[^/]+$|;
+    push @ibase, $1 if $in =~ m|^(.+)/[^/]+$|;
 } else {
     $inf = \*STDIN;
 }
 } else {
     $inf = \*STDIN;
 }
@@ -73,16 +78,16 @@ if (defined $out) {
 }
 
 while(defined $inf) {
 }
 
 while(defined $inf) {
-while(<$inf>) {
+INF: while(<$inf>) {
     # Certain commands are discarded without further processing.
     /^\@(?:
     # Certain commands are discarded without further processing.
     /^\@(?:
-        [a-z]+index            # @*index: useful only in complete manual
-        |need                  # @need: useful only in printed manual
-        |(?:end\s+)?group      # @group .. @end group: ditto
-        |page                  # @page: ditto
-        |node                  # @node: useful only in .info file
-        |(?:end\s+)?ifnottex   # @ifnottex .. @end ifnottex: use contents
-       )\b/x and next;
+         [a-z]+index            # @*index: useful only in complete manual
+         |need                  # @need: useful only in printed manual
+         |(?:end\s+)?group      # @group .. @end group: ditto
+         |page                  # @page: ditto
+         |node                  # @node: useful only in .info file
+         |(?:end\s+)?ifnottex   # @ifnottex .. @end ifnottex: use contents
+        )\b/x and next;
 
     chomp;
 
 
     chomp;
 
@@ -92,38 +97,43 @@ while(<$inf>) {
 
     # Identify a man title but keep only the one we are interested in.
     /^\@c\s+man\s+title\s+([A-Za-z0-9-]+)\s+(.+)/ and do {
 
     # Identify a man title but keep only the one we are interested in.
     /^\@c\s+man\s+title\s+([A-Za-z0-9-]+)\s+(.+)/ and do {
-       if (exists $defs{$1}) {
-           $fn = $1;
-           $tl = postprocess($2);
-       }
-       next;
+        if (exists $defs{$1}) {
+            $fn = $1;
+            $tl = postprocess($2);
+        }
+        next;
+    };
+
+    /^\@include\s+(.+)$/ and do {
+        push @instack, $inf;
+        $inf = gensym();
+
+        for (@ibase) {
+            open($inf, "<" . $_ . "/" . $1) and next INF;
+        }
+        die "cannot open $1: $!\n";
     };
 
     # Look for blocks surrounded by @c man begin SECTION ... @c man end.
     # This really oughta be @ifman ... @end ifman and the like, but such
     # would require rev'ing all other Texinfo translators.
     };
 
     # Look for blocks surrounded by @c man begin SECTION ... @c man end.
     # This really oughta be @ifman ... @end ifman and the like, but such
     # would require rev'ing all other Texinfo translators.
-    /^\@c\s+man\s+begin\s+([A-Z]+)\s+([A-Za-z0-9-]+)/ and do {
-       $output = 1 if exists $defs{$2};
-        $sect = $1;
-       next;
-    };
-    /^\@c\s+man\s+begin\s+([A-Z]+)/ and $sect = $1, $output = 1, next;
+    /^\@c\s+man\s+begin\s+([A-Za-z ]+)/ and $sect = $1, push (@sects_sequence, $sect), $output = 1, next;
     /^\@c\s+man\s+end/ and do {
     /^\@c\s+man\s+end/ and do {
-       $sects{$sect} = "" unless exists $sects{$sect};
-       $sects{$sect} .= postprocess($section);
-       $section = "";
-       $output = 0;
-       next;
+        $sects{$sect} = "" unless exists $sects{$sect};
+        $sects{$sect} .= postprocess($section);
+        $section = "";
+        $output = 0;
+        next;
     };
 
     # handle variables
     /^\@set\s+([a-zA-Z0-9_-]+)\s*(.*)$/ and do {
     };
 
     # handle variables
     /^\@set\s+([a-zA-Z0-9_-]+)\s*(.*)$/ and do {
-       $defs{$1} = $2;
-       next;
+        $defs{$1} = $2;
+        next;
     };
     /^\@clear\s+([a-zA-Z0-9_-]+)/ and do {
     };
     /^\@clear\s+([a-zA-Z0-9_-]+)/ and do {
-       delete $defs{$1};
-       next;
+        delete $defs{$1};
+        next;
     };
 
     next unless $output;
     };
 
     next unless $output;
@@ -135,55 +145,55 @@ while(<$inf>) {
     # End-block handler goes up here because it needs to operate even
     # if we are skipping.
     /^\@end\s+([a-z]+)/ and do {
     # End-block handler goes up here because it needs to operate even
     # if we are skipping.
     /^\@end\s+([a-z]+)/ and do {
-       # Ignore @end foo, where foo is not an operation which may
-       # cause us to skip, if we are presently skipping.
-       my $ended = $1;
-       next if $skipping && $ended !~ /^(?:ifset|ifclear|ignore|menu|iftex)$/;
-
-       die "\@end $ended without \@$ended at line $.\n" unless defined $endw;
-       die "\@$endw ended by \@end $ended at line $.\n" unless $ended eq $endw;
-
-       $endw = pop @endwstack;
-
-       if ($ended =~ /^(?:ifset|ifclear|ignore|menu|iftex)$/) {
-           $skipping = pop @skstack;
-           next;
-       } elsif ($ended =~ /^(?:example|smallexample|display)$/) {
-           $shift = "";
-           $_ = "";    # need a paragraph break
-       } elsif ($ended =~ /^(?:itemize|enumerate|[fv]?table)$/) {
-           $_ = "\n=back\n";
-           $ic = pop @icstack;
-       } else {
-           die "unknown command \@end $ended at line $.\n";
-       }
+        # Ignore @end foo, where foo is not an operation which may
+        # cause us to skip, if we are presently skipping.
+        my $ended = $1;
+        next if $skipping && $ended !~ /^(?:ifset|ifclear|ignore|menu|iftex)$/;
+
+        die "\@end $ended without \@$ended at line $.\n" unless defined $endw;
+        die "\@$endw ended by \@end $ended at line $.\n" unless $ended eq $endw;
+
+        $endw = pop @endwstack;
+
+        if ($ended =~ /^(?:ifset|ifclear|ignore|menu|iftex)$/) {
+            $skipping = pop @skstack;
+            next;
+        } elsif ($ended =~ /^(?:example|smallexample|display)$/) {
+            $shift = "";
+            $_ = "";        # need a paragraph break
+        } elsif ($ended =~ /^(?:itemize|enumerate|[fv]?table)$/) {
+            $_ = "\n=back\n";
+            $ic = pop @icstack;
+        } else {
+            die "unknown command \@end $ended at line $.\n";
+        }
     };
 
     # We must handle commands which can cause skipping even while we
     # are skipping, otherwise we will not process nested conditionals
     # correctly.
     /^\@ifset\s+([a-zA-Z0-9_-]+)/ and do {
     };
 
     # We must handle commands which can cause skipping even while we
     # are skipping, otherwise we will not process nested conditionals
     # correctly.
     /^\@ifset\s+([a-zA-Z0-9_-]+)/ and do {
-       push @endwstack, $endw;
-       push @skstack, $skipping;
-       $endw = "ifset";
-       $skipping = 1 unless exists $defs{$1};
-       next;
+        push @endwstack, $endw;
+        push @skstack, $skipping;
+        $endw = "ifset";
+        $skipping = 1 unless exists $defs{$1};
+        next;
     };
 
     /^\@ifclear\s+([a-zA-Z0-9_-]+)/ and do {
     };
 
     /^\@ifclear\s+([a-zA-Z0-9_-]+)/ and do {
-       push @endwstack, $endw;
-       push @skstack, $skipping;
-       $endw = "ifclear";
-       $skipping = 1 if exists $defs{$1};
-       next;
+        push @endwstack, $endw;
+        push @skstack, $skipping;
+        $endw = "ifclear";
+        $skipping = 1 if exists $defs{$1};
+        next;
     };
 
     /^\@(ignore|menu|iftex)\b/ and do {
     };
 
     /^\@(ignore|menu|iftex)\b/ and do {
-       push @endwstack, $endw;
-       push @skstack, $skipping;
-       $endw = $1;
-       $skipping = 1;
-       next;
+        push @endwstack, $endw;
+        push @skstack, $skipping;
+        $endw = $1;
+        $skipping = 1;
+        next;
     };
 
     next if $skipping;
     };
 
     next if $skipping;
@@ -210,85 +220,76 @@ while(<$inf>) {
 
     # Inside a verbatim block, handle @var specially.
     if ($shift ne "") {
 
     # Inside a verbatim block, handle @var specially.
     if ($shift ne "") {
-       s/\@var\{([^\}]*)\}/<$1>/g;
+        s/\@var\{([^\}]*)\}/<$1>/g;
     }
 
     # POD doesn't interpret E<> inside a verbatim block.
     if ($shift eq "") {
     }
 
     # POD doesn't interpret E<> inside a verbatim block.
     if ($shift eq "") {
-       s/</&lt;/g;
-       s/>/&gt;/g;
+        s/</&lt;/g;
+        s/>/&gt;/g;
     } else {
     } else {
-       s/</&LT;/g;
-       s/>/&GT;/g;
+        s/</&LT;/g;
+        s/>/&GT;/g;
     }
 
     # Single line command handlers.
 
     }
 
     # Single line command handlers.
 
-    /^\@include\s+(.+)$/ and do {
-       push @instack, $inf;
-       $inf = gensym();
-
-       # Try cwd and $ibase.
-       open($inf, "<" . $1)
-           or open($inf, "<" . $ibase . "/" . $1)
-               or die "cannot open $1 or $ibase/$1: $!\n";
-       next;
-    };
-
-    /^\@(?:section|unnumbered|unnumberedsec|center)\s+(.+)$/
-       and $_ = "\n=head2 $1\n";
-    /^\@subsection\s+(.+)$/
-       and $_ = "\n=head3 $1\n";
+    /^\@(?:section|unnumbered|unnumberedsec|center|heading)\s+(.+)$/
+        and $_ = "\n=head2 $1\n";
+    /^\@(?:subsection|subheading)\s+(.+)$/
+        and $_ = "\n=head3 $1\n";
+    /^\@(?:subsubsection|subsubheading)\s+(.+)$/
+        and $_ = "\n=head4 $1\n";
 
     # Block command handlers:
 
     # Block command handlers:
-    /^\@itemize\s+(\@[a-z]+|\*|-)/ and do {
-       push @endwstack, $endw;
-       push @icstack, $ic;
-       $ic = $1;
-       $_ = "\n=over 4\n";
-       $endw = "itemize";
+    /^\@itemize\s*(\@[a-z]+|\*|-)?/ and do {
+        push @endwstack, $endw;
+        push @icstack, $ic;
+        $ic = $1 ? $1 : "*";
+        $_ = "\n=over 4\n";
+        $endw = "itemize";
     };
 
     /^\@enumerate(?:\s+([a-zA-Z0-9]+))?/ and do {
     };
 
     /^\@enumerate(?:\s+([a-zA-Z0-9]+))?/ and do {
-       push @endwstack, $endw;
-       push @icstack, $ic;
-       if (defined $1) {
-           $ic = $1 . ".";
-       } else {
-           $ic = "1.";
-       }
-       $_ = "\n=over 4\n";
-       $endw = "enumerate";
+        push @endwstack, $endw;
+        push @icstack, $ic;
+        if (defined $1) {
+            $ic = $1 . ".";
+        } else {
+            $ic = "1.";
+        }
+        $_ = "\n=over 4\n";
+        $endw = "enumerate";
     };
 
     /^\@([fv]?table)\s+(\@[a-z]+)/ and do {
     };
 
     /^\@([fv]?table)\s+(\@[a-z]+)/ and do {
-       push @endwstack, $endw;
-       push @icstack, $ic;
-       $endw = $1;
-       $ic = $2;
-       $ic =~ s/\@(?:samp|strong|key|gcctabopt|option|env)/B/;
-       $ic =~ s/\@(?:code|kbd)/C/;
-       $ic =~ s/\@(?:dfn|var|emph|cite|i)/I/;
-       $ic =~ s/\@(?:file)/F/;
-       $_ = "\n=over 4\n";
+        push @endwstack, $endw;
+        push @icstack, $ic;
+        $endw = $1;
+        $ic = $2;
+        $ic =~ s/\@(?:samp|strong|key|gcctabopt|option|env)/B/;
+        $ic =~ s/\@(?:code|kbd)/C/;
+        $ic =~ s/\@(?:dfn|var|emph|cite|i)/I/;
+        $ic =~ s/\@(?:file)/F/;
+        $_ = "\n=over 4\n";
     };
 
     /^\@((?:small)?example|display)/ and do {
     };
 
     /^\@((?:small)?example|display)/ and do {
-       push @endwstack, $endw;
-       $endw = $1;
-       $shift = "\t";
-       $_ = "";        # need a paragraph break
+        push @endwstack, $endw;
+        $endw = $1;
+        $shift = "\t";
+        $_ = "";        # need a paragraph break
     };
 
     /^\@itemx?\s*(.+)?$/ and do {
     };
 
     /^\@itemx?\s*(.+)?$/ and do {
-       if (defined $1) {
-           # Entity escapes prevent munging by the <> processing below.
-           $_ = "\n=item $ic\&LT;$1\&GT;\n";
-       } else {
-           $_ = "\n=item $ic\n";
-           $ic =~ y/A-Ya-y/B-Zb-z/;
-           $ic =~ s/(\d+)/$1 + 1/eg;
-       }
+        if (defined $1) {
+            # Entity escapes prevent munging by the <> processing below.
+            $_ = "\n=item $ic\&LT;$1\&GT;\n";
+        } else {
+            $_ = "\n=item $ic\n";
+            $ic =~ y/A-Ya-y/B-Zb-z/;
+            $ic =~ s/(\d+)/$1 + 1/eg;
+        }
     };
 
     $section .= $shift.$_."\n";
     };
 
     $section .= $shift.$_."\n";
@@ -303,14 +304,14 @@ die "No filename or title\n" unless defined $fn && defined $tl;
 $sects{NAME} = "$fn \- $tl\n";
 $sects{FOOTNOTES} .= "=back\n" if exists $sects{FOOTNOTES};
 
 $sects{NAME} = "$fn \- $tl\n";
 $sects{FOOTNOTES} .= "=back\n" if exists $sects{FOOTNOTES};
 
-for $sect (qw(NAME SYNOPSIS DESCRIPTION OPTIONS EXAMPLES ENVIRONMENT FILES
-             BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
+unshift @sects_sequence, "NAME";
+for $sect (@sects_sequence) {
     if(exists $sects{$sect}) {
     if(exists $sects{$sect}) {
-       $head = $sect;
-       $head =~ s/SEEALSO/SEE ALSO/;
-       print "=head1 $head\n\n";
-       print scalar unmunge ($sects{$sect});
-       print "\n";
+        $head = $sect;
+        $head =~ s/SEEALSO/SEE ALSO/;
+        print "=head1 $head\n\n";
+        print scalar unmunge ($sects{$sect});
+        print "\n";
     }
 }
 
     }
 }
 
@@ -325,13 +326,13 @@ sub postprocess
 
     # @value{foo} is replaced by whatever 'foo' is defined as.
     while (m/(\@value\{([a-zA-Z0-9_-]+)\})/g) {
 
     # @value{foo} is replaced by whatever 'foo' is defined as.
     while (m/(\@value\{([a-zA-Z0-9_-]+)\})/g) {
-       if (! exists $defs{$2}) {
-           print STDERR "Option $2 not defined\n";
-           s/\Q$1\E//;
-       } else {
-           $value = $defs{$2};
-           s/\Q$1\E/$value/;
-       }
+        if (! exists $defs{$2}) {
+            print STDERR "Option $2 not defined\n";
+            s/\Q$1\E//;
+        } else {
+            $value = $defs{$2};
+            s/\Q$1\E/$value/;
+        }
     }
 
     # Formatting commands.
     }
 
     # Formatting commands.
@@ -350,9 +351,11 @@ sub postprocess
     # @* is also impossible in .pod; we discard it and any newline that
     # follows it.  Similarly, our macro @gol must be discarded.
 
     # @* is also impossible in .pod; we discard it and any newline that
     # follows it.  Similarly, our macro @gol must be discarded.
 
+    s/\@anchor{(?:[^\}]*)\}//g;
     s/\(?\@xref\{(?:[^\}]*)\}(?:[^.<]|(?:<[^<>]*>))*\.\)?//g;
     s/\s+\(\@pxref\{(?:[^\}]*)\}\)//g;
     s/;\s+\@pxref\{(?:[^\}]*)\}//g;
     s/\(?\@xref\{(?:[^\}]*)\}(?:[^.<]|(?:<[^<>]*>))*\.\)?//g;
     s/\s+\(\@pxref\{(?:[^\}]*)\}\)//g;
     s/;\s+\@pxref\{(?:[^\}]*)\}//g;
+    s/\@ref\{([^\}]*)\}/$1/g;
     s/\@noindent\s*//g;
     s/\@refill//g;
     s/\@gol//g;
     s/\@noindent\s*//g;
     s/\@refill//g;
     s/\@gol//g;
@@ -381,9 +384,9 @@ sub postprocess
     # processing because otherwise the regexp will choke on formatting
     # inside @footnote.
     while (/\@footnote/g) {
     # processing because otherwise the regexp will choke on formatting
     # inside @footnote.
     while (/\@footnote/g) {
-       s/\@footnote\{([^\}]+)\}/[$fnno]/;
-       add_footnote($1, $fnno);
-       $fnno++;
+        s/\@footnote\{([^\}]+)\}/[$fnno]/;
+        add_footnote($1, $fnno);
+        $fnno++;
     }
 
     return $_;
     }
 
     return $_;
@@ -406,7 +409,7 @@ sub unmunge
 sub add_footnote
 {
     unless (exists $sects{FOOTNOTES}) {
 sub add_footnote
 {
     unless (exists $sects{FOOTNOTES}) {
-       $sects{FOOTNOTES} = "\n=over 4\n\n";
+        $sects{FOOTNOTES} = "\n=over 4\n\n";
     }
 
     $sects{FOOTNOTES} .= "=item $fnno.\n\n"; $fnno++;
     }
 
     $sects{FOOTNOTES} .= "=item $fnno.\n\n"; $fnno++;
@@ -419,9 +422,9 @@ sub add_footnote
     my $genseq = 0;
     sub gensym
     {
     my $genseq = 0;
     sub gensym
     {
-       my $name = "GEN" . $genseq++;
-       my $ref = \*{$name};
-       delete $::{$name};
-       return $ref;
+        my $name = "GEN" . $genseq++;
+        my $ref = \*{$name};
+        delete $::{$name};
+        return $ref;
     }
 }
     }
 }