Provided by: texlive-latex-extra_2018.20190227-1_all bug


       perltex - enable LaTeX macros to be defined in terms of Perl code


       perltex [--help] [--latex=program] [--[no]safe] [--permit=feature] [--makesty] [latex


       LaTeX -- through the underlying TeX typesetting system -- produces beautifully typeset
       documents but has a macro language that is difficult to program.  In particular, support
       for complex string manipulation is largely lacking.  Perl is a popular general-purpose
       programming language whose forte is string manipulation.  However, it has no typesetting
       capabilities whatsoever.

       Clearly, Perl's programmability could complement LaTeX's typesetting strengths.  perltex
       is the tool that enables a symbiosis between the two systems.  All a user needs to do is
       compile a LaTeX document using perltex instead of latex.  (perltex is actually a wrapper
       for latex, so no latex functionality is lost.)  If the document includes a
       "\usepackage{perltex}" in its preamble, then "\perlnewcommand" and "\perlrenewcommand"
       macros will be made available.  These behave just like LaTeX's "\newcommand" and
       "\renewcommand" except that the macro body contains Perl code instead of LaTeX code.


       perltex accepts the following command-line options:

           Display basic usage information.

           Specify a program to use instead of latex.  For example, "--latex=pdflatex" would
           typeset the given document using pdflatex instead of ordinary latex.

           Enable or disable sandboxing.  With the default of --safe, perltex executes the code
           from a "\perlnewcommand" or "\perlrenewcommand" macro within a protected environment
           that prohibits ``unsafe'' operations such as accessing files or executing external
           programs.  Specifying --nosafe gives the LaTeX document carte blanche to execute any
           arbitrary Perl code, including that which can harm the user's files.  See Safe for
           more information.

           Permit particular Perl operations to be performed.  The --permit option, which can be
           specified more than once on the command line, enables finer-grained control over the
           perltex sandbox.  See Opcode for more information.

           Generate a LaTeX style file called noperltex.sty.  Replacing the document's
           "\usepackage{perltex}" line with "\usepackage{noperltex}" produces the same output but
           does not require PerlTeX, making the document suitable for distribution to people who
           do not have PerlTeX installed.  The disadvantage is that noperltex.sty is specific to
           the document that produced it.  Any changes to the document's PerlTeX macro
           definitions or macro invocations necessitates rerunning perltex with the --makesty

       These options are then followed by whatever options are normally passed to latex (or
       whatever program was specified with "--latex"), including, for instance, the name of the
       .tex file to compile.


       In its simplest form, perltex is run just like latex:

           perltex myfile.tex

       To use pdflatex instead of regular latex, use the --latex option:

           perltex --latex=pdflatex myfile.tex

       If LaTeX gives a ``"trapped by operation mask"'' error and you trust the .tex file you're
       trying to compile not to execute malicious Perl code (e.g., because you wrote it
       yourself), you can disable perltex's safety mechansisms with --nosafe:

           perltex --nosafe myfile.tex

       The following command gives documents only perltex's default permissions (":browse") plus
       the ability to open files and invoke the "time" command:

           perltex --permit=:browse --permit=:filesys_open
             --permit=time myfile.tex


       perltex honors the following environment variables:

           Specify the filename of the LaTeX compiler.  The LaTeX compiler defaults to
           ``"latex"''.  The "PERLTEX" environment variable overrides this default, and the
           --latex command-line option (see "OPTIONS") overrides that.


       While compiling jobname.tex, perltex makes use of the following files:

           log file written by Perl; helpful for debugging Perl macros

           information sent from LaTeX to Perl

           information sent from Perl to LaTeX

           ``flag'' file whose existence indicates that jobname.topl contains valid data

           ``flag'' file whose existence indicates that jobname.frpl contains valid data

           ``flag'' file whose existence indicates that jobname.ffpl has been deleted

           file generated by noperltex.sty for each PerlTeX macro invocation


       perltex's sandbox defaults to what Opcode calls ``":browse"''.


       latex(1), pdflatex(1), perl(1), Safe(3pm), Opcode(3pm)


       Scott Pakin,