home *** CD-ROM | disk | FTP | other *** search
/ BURKS 2 / BURKS_AUG97.ISO / SLAKWARE / D12 / PERL1.TGZ / perl1.tar / usr / bin / pod2latex (.txt) < prev    next >
LaTeX Document  |  1996-06-28  |  22KB  |  529 lines
  1. #!/usr/bin/perl
  2.     eval 'exec perl -S $0 "$@"'
  3.     if 0;
  4. # pod2latex, version 1.1
  5. # by Taro Kawagish (kawagish@imslab.co.jp),  Jan 11, 1995.
  6. # pod2latex filters Perl pod documents to LaTeX documents.
  7. # What pod2latex does:
  8. # 1. Pod file 'perl_doc_entry.pod' is filtered to 'perl_doc_entry.tex'.
  9. # 2. Indented paragraphs are translated into
  10. #    '\begin{verbatim} ... \end{verbatim}'.
  11. # 3. '=head1 heading' command is translated into '\section{heading}'
  12. # 4. '=head2 heading' command is translated into '\subsection*{heading}'
  13. # 5. '=over N' command is translated into
  14. #        '\begin{itemize}'    if following =item starts with *,
  15. #        '\begin{enumerate}'    if following =item starts with 1.,
  16. #        '\begin{description}'    if else.
  17. #      (indentation level N is ignored.)
  18. # 6. '=item * heading' command is translated into '\item heading',
  19. #    '=item 1. heading' command is translated into '\item heading',
  20. #    '=item heading' command(other) is translated into '\item[heading]'.
  21. # 7. '=back' command is translated into
  22. #        '\end{itemize}'    if started with '\begin{itemize}',
  23. #        '\end{enumerate}'    if started with '\begin{enumerate}',
  24. #        '\end{description}'    if started with '\begin{description}'.
  25. # 8. other paragraphs are translated into strings with TeX special characters
  26. #    escaped.
  27. # 9. In heading text, and other paragraphs, the following translation of pod
  28. #    quotes are done, and then TeX special characters are escaped after that.
  29. #      I<text> to {\em text\/},
  30. #      B<text> to {\bf text},
  31. #      S<text> to text1,
  32. #        where text1 is a string with blank characters replaced with ~,
  33. #      C<text> to {\tt text2},
  34. #        where text2 is a string with TeX special characters escaped to
  35. #        obtain a literal printout,
  36. #      E<text> (HTML escape) to TeX escaped string,
  37. #      L<text> to referencing string as is done by pod2man,
  38. #      F<file> to {\em file\/},
  39. #      Z<> to a null string,
  40. # 10. those headings are indexed:
  41. #       '=head1 heading'   =>  \section{heading}\index{heading}
  42. #       '=head2 heading'   =>  \subsection*{heading}\index{heading}
  43. #                 only when heading does not match frequent patterns such as
  44. #                 DESCRIPTION, DIAGNOSTICS,...
  45. #       '=item heading'   =>  \item{heading}\index{heading}
  46. # Usage:
  47. #     pod2latex perl_doc_entry.pod
  48. # this will write to a file 'perl_doc_entry.tex'.
  49. # To LaTeX:
  50. # The following commands need to be defined in the preamble of the LaTeX
  51. # document:
  52. # \def\C++{{\rm C\kern-.05em\raise.3ex\hbox{\footnotesize ++}}}
  53. # \def\underscore{\leavevmode\kern.04em\vbox{\hrule width 0.4em height 0.3pt}}
  54. # and \parindent should be set zero:
  55. # \setlength{\parindent}{0pt}
  56. # Note:
  57. # This script was written modifing pod2man.
  58. # Bug:
  59. # If HTML escapes E<text> other than E<amp>,E<lt>,E<gt>,E<quot> are used
  60. # in C<>, translation will produce wrong character strings.
  61. # Translation of HTML escapes of various European accents might be wrong.
  62. $/ = "";            # record separator is blank lines
  63. # TeX special characters.
  64. ##$tt_ables = "!@*()-=+|;:'\"`,./?<>";
  65. $backslash_escapables = "#\$%&{}_";
  66. $backslash_escapables2 = "#\$%&{}";    # except _
  67. ##$nonverbables = "^\\~";
  68. ##$bracketesc = "[]";
  69. ##@tex_verb_fences = unpack("aaaaaaaaa","|#@!*+?:;");
  70. @head1_freq_patterns        # =head1 patterns which need not be index'ed
  71.     = ("AUTHOR","Author","BUGS","DATE","DESCRIPTION","DIAGNOSTICS",
  72.        "ENVIRONMENT","EXAMPLES","FILES","INTRODUCTION","NAME","NOTE",
  73.        "SEE ALSO","SYNOPSIS","WARNING");
  74. $indent = 0;
  75. # parse the pods, produce LaTeX.
  76. open(POD,"<$ARGV[0]") || die "cant open $ARGV[0]";
  77. ($pod=$ARGV[0]) =~ s/\.pod$//;
  78. open(LATEX,">$pod.tex");
  79. &do_hdr();
  80. $cutting = 1;
  81. while (<POD>) {
  82.     if ($cutting) {
  83.     next unless /^=/;
  84.     $cutting = 0;
  85.     }
  86.     chop;
  87.     length || (print LATEX  "\n") && next;
  88.     # translate indented lines as a verabatim paragraph
  89.     if (/^\s/) {
  90.     @lines = split(/\n/);
  91.     print LATEX  "\\begin{verbatim}\n";
  92.     for (@lines) {
  93.         1 while s
  94.         {^( [^\t]* ) \t ( \t* ) }
  95.         { $1 . ' ' x (8 - (length($1)%8) + 8*(length($2))) }ex;
  96.         print LATEX  $_,"\n";
  97.     print LATEX  "\\end{verbatim}\n";
  98.     next;
  99.     }
  100.     # preserve '=item' line with pod quotes as they are.
  101.     if (/^=item/) {
  102.     ($bareitem = $_) =~ s/^=item\s*//;
  103.     }
  104.     # check for things that'll hosed our noremap scheme; affects $_
  105.     &init_noremap();
  106.     # expand strings "func()" as pod quotes.
  107.     if (!/^=item/) {
  108.     # first hide pod escapes.
  109.     # escaped strings are mapped into the ones with the MSB's on.
  110.     s/([A-Z]<[^<>]*>)/noremap($1)/ge;
  111.     # func() is a reference to a perl function
  112.     s{\b([:\w]+\(\))}{I<$1>}g;
  113.     # func(n) is a reference to a man page
  114.     s{(\w+)(\([^\s,\051]+\))}{I<$1>$2}g;
  115.     # convert simple variable references
  116. #    s/([\$\@%][\w:]+)/C<$1>/g;
  117. #    s/\$[\w:]+\[[0-9]+\]/C<$&>/g;
  118.     if (m{ ([\-\w]+\([^\051]*?[\@\$,][^\051]*?\))
  119.            }x && $` !~ /([LCI]<[^<>]*|-)$/ && !/^=\w/)
  120.         warn "``$1'' should be a [LCI]<$1> ref";
  121.     while (/(-[a-zA-Z])\b/g && $` !~ /[\w\-]$/) {
  122.         warn "``$1'' should be [CB]<$1> ref";
  123.     # put back pod quotes so we get the inside of <> processed;
  124.     $_ = &clear_noremap($_);
  125.     }
  126.     # process TeX special characters
  127.     # First hide HTML quotes E<> since they can be included in C<>.
  128.     s/(E<[^<>]+>)/noremap($1)/ge;
  129.     # Then hide C<> type literal quotes.
  130.     # String inside of C<> will later be expanded into {\tt ..} strings
  131.     # with TeX special characters escaped as needed.
  132.     s/(C<[^<>]*>)/&noremap($1)/ge;
  133.     # Next escape TeX special characters including other pod quotes B< >,...
  134.     #
  135.     # NOTE: s/re/&func($str)/e evaluates $str just once in perl5.
  136.     # (in perl4 evaluation takes place twice before getting passed to func().)
  137.     # - hyphen => ---
  138.     s/(\S+)(\s+)-+(\s+)(\S+)/"$1".&noremap(" --- ")."$4"/ge;
  139.     # '-', '--', "-"  =>  '{\tt -}', '{\tt --}', "{\tt -}"
  140. ##    s/("|')(\s*)(-+)(\s*)\1/&noremap("$1$2\{\\tt $3\}$4$1")/ge;
  141. ## changed Wed Jan 25 15:26:39 JST 1995
  142.     # '-', '--', "-"  =>  '$-$', '$--$', "$-$"
  143.     s/(\s+)(['"])(-+)([^'"\-]*)\2(\s+|[,.])/"$1$2".&noremap("\$$3\$")."$4$2$5"/ge;
  144.     s/(\s+)(['"])([^'"\-]*)(-+)(\s*)\2(\s+|[,.])/"$1$2$3".&noremap("\$$4\$")."$5$2$6"/ge;
  145.     # (--|-)  =>  ($--$|$-$)
  146.     s/(\s+)\((-+)([=@%\$\+\\\|\w]*)(-*)([=@%\$\+\\\|\w]*)\)(\s+|[,.])/"$1\(".&noremap("\$$2\$")."$3".&noremap("\$$4\$")."$5\)$6"/ge;
  147.     # numeral -  =>  $-$
  148.     s/(\(|[0-9]+|\s+)-(\s*\(?\s*[0-9]+)/&noremap("$1\$-\$$2")/ge;
  149.     # -- in quotes  =>  two separate -
  150.     s/B<([^<>]*)--([^<>]*)>/&noremap("B<$1\{\\tt --\}$2>")/ge;
  151.     # backslash escapable characters except _.
  152.     s/([$backslash_escapables2])/&noremap("\\$1")/ge;
  153.     s/_/&noremap("\\underscore{}")/ge;        # a litle thicker than \_.
  154.     # quote TeX special characters |, ^, ~, \.
  155.     s/\|/&noremap("\$|\$")/ge;
  156.     s/\^/&noremap("\$\\hat{\\hspace{0.4em}}\$")/ge;
  157.     s/\~/&noremap("\$\\tilde{\\hspace{0.4em}}\$")/ge;
  158.     s/\\/&noremap("\$\\backslash{}\$")/ge;
  159.     # quote [ and ] to be used in \item[]
  160.     s/([\[\]])/&noremap("{\\tt $1}")/ge;
  161.     # characters need to be treated differently in TeX
  162.     # keep * if an item heading
  163.     s/^(=item[ \t]+)[*]((.|\n)*)/"$1" . &noremap("*") . "$2"/ge;
  164.     s/[*]/&noremap("\$\\ast\$")/ge;    # other *
  165.     # hide other pod quotes.
  166.     s/([ABD-Z]<[^<>]*>)/&noremap($1)/ge;
  167.     # escape < and > as math strings,
  168.     # now that we are done with hiding pod <> quotes.
  169.     s/</&noremap("\$<\$")/ge;
  170.     s/>/&noremap("\$>\$")/ge;
  171.     # put it back so we get the <> processed again;
  172.     $_ = &clear_noremap($_);
  173.     # Expand pod quotes recursively:
  174.     # (1) type face directives [BIFS]<[^<>]*> to appropriate TeX commands,
  175.     # (2) L<[^<>]*> to reference strings,
  176.     # (3) C<[^<>]*> to TeX literal quotes,
  177.     # (4) HTML quotes E<> inside of C<> quotes.
  178.     # Hide E<> again since they can be included in C<>.
  179.     s/(E<[^<>]+>)/noremap($1)/ge;
  180.     $maxnest = 10;
  181.     while ($maxnest-- && /[A-Z]</) {
  182.     # bold and italic quotes
  183.     s/B<([^<>]*)>/"{\\bf $1}"/eg;
  184.     s#I<([^<>]*)>#"{\\em $1\\/}"#eg;
  185.     # files and filelike refs in italics
  186.     s#F<([^<>]*)>#"{\\em $1\\/}"#eg;
  187.     # no break quote -- usually we want C<> for this
  188.     s/S<([^<>]*)>/&nobreak($1)/eg;
  189.     # LREF: a manpage(3f)
  190.     s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))?>:the {\\em $1\\/}$2 manpage:g;