LISTING(1) User Contributed Perl Documentation LISTING(1) NNNNAAAAMMMMEEEE listing - C++ / Perl to LaTeX converter SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS lllliiiissssttttiiiinnnngggg _o_p_t_i_o_n_s _f_i_l_e_n_a_m_e_s where _f_i_l_e_n_a_m_e_s is a sequence of C++ or Perl files (mixing allowed). DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN lllliiiissssttttiiiinnnngggg converts the files to a single LaTeX file listing.tex and runs latex, dvips and psnup on it. The results are a DVI file listing.dvi, a Postscript file listing1.ps (1 page/sheet), and a Postscript file listing.ps (2 pages/sheet). o Keywords, C++ preprocessor commands, strings and comments are typeset in different fonts. o Font size varies with nesting level ({...}). o LaTeX verbatim comments in the styles /*tex...*/, //tex..., //\section... (resp for Perl #tex... etc) allow you to embed pictures and formulas in your comments. o A table of contents (TOC) is produced. o Identifiers can be collected in an index. (option --index) For the first occurrence of each identifier, a \label- command can be generated, so you can use \pageref in your LaTeX comments to refer to definitions. (option --references) o Perl POD inline documentation is automatically run through pod2latex and included in the resulting LaTeX file. OOOOPPPPTTTTIIIIOOOONNNNSSSS lllliiiissssttttiiiinnnngggg is highly configurable, taking options from the command line as well as the environment variable LLLLIIIISSSSTTTTIIIINNNNGGGG. Valid options are listed in the following. For each option, both the short and long form are given. -v --version prints the version number and exits. -b --begin
includes the file
at the place where otherwise the LaTeX-command \begin{document} would stand. By default, if a file named begin.tex exists in the current working directory, it is included in that place, otherwise just the \begin{document} statement is produced. 4/Feb/98 perl 5.004 1 LISTING(1) User Contributed Perl Documentation LISTING(1) -l --listing uses the filenames .tex, .dvi etc instead of listing.tex, listing.dvi etc. as output file names. -st --styles uses the LaTeX2e style files in the \documentclass statement as "options". The files must be comma-separated (but no spaces!). Default is 'fleqn,twoside'. -pa --packages includes the LaTeX packages by \usepackage statements. The files must be comma- separated (but no spaces!). Default is 'a4'. The package makeidx is always appended to the list unless the option --noindex is given, and the package psfig is always prepended to the list unless --nopsfig is given. --print causes lllliiiissssttttiiiinnnngggg to pipe the resulting file (1 page/sheet) to the print command . This option implies --latex, --noxdvi, and --quiet. A useful print command looks like "lpr -Plp". --print2 causes lllliiiissssttttiiiinnnngggg to pipe the resulting file (2 pages/sheet) to the print command . This option implies --latex, --noxdvi, and --quiet. A useful print command looks like "lpr -Plp". Now comes a list of options that can be set or unset. You can unset an option by prefixing it with a 'no' (e.g., --nolatex). This is particularly useful with options that are set by default. -q --quiet causes lllliiiissssttttiiiinnnngggg not to list the conversions going on. Also, the LaTeX/dvips/xdvi/psnup output and stderr is piped to /dev/null. Off by default. -l --latex causes lllliiiissssttttiiiinnnngggg to call latex/dvips/psnup after it has finished the conversion process. On by default. -x --xdvi causes lllliiiissssttttiiiinnnngggg to call xdvi after it has finished running latex. Implies --latex if set. Off by default. -ps --psfig puts a "psfig" in front of the style file list. 4/Feb/98 perl 5.004 2 LISTING(1) User Contributed Perl Documentation LISTING(1) This enables use of the \psfig command in your LaTeX-comments. On by default. -i --index causes lllliiiissssttttiiiinnnngggg to produce an index of words found in the source. Implies option --references. Off by default. -t --toc causes lllliiiissssttttiiiinnnngggg to produce a table of contents, which is however empty unless you set option --sections or write embedded LaTeX statements such as //\section{...} to generate entries. On by default. -sy --symbols causes lllliiiissssttttiiiinnnngggg to typeset certain special symbols (like Greek letters) in LaTeX's symbol font. On by default. -se --sections produces a \section-command at the top of each file in the lllliiiissssttttiiiinnnngggg. You can have the same effect by putting a #\section{...}-like comment on the first line of each file. Off by default to encourage you to play around with LaTeX comments. -fo --formfeeds includes a \clearpage-command between files, so each file will start on a new page. On by default. -r --references produces a \label-command on every first occurence of an identifier, so you can use \pageref to refer to the page where an identifier is first declared. Off by default. -pre --preservepod preserves the original output of pod2latex for embedded POD (inline documentation). Otherwise, lllliiiissssttttiiiinnnngggg cuts off the pod2latex generated \section- command and downgrades subsequent \subsections and \subsubsections of POD documentation to \subsubsections and \paragraphs. This default should make your POD documentation look nicely embedded in the listing if you arrange each source file as a LaTeX \section, then inside the source code use \subsections. The POD then fills one \subsection, being arranged into \subsubsections and \paragraphs. Off by default. EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT 4/Feb/98 perl 5.004 3 LISTING(1) User Contributed Perl Documentation LISTING(1) LISTING Default arguments. These are simply prepended to the command line argument on every call of lllliiiissssttttiiiinnnngggg. FFFFIIIILLLLEEEESSSS /usr/local/bin/listing The lllliiiissssttttiiiinnnngggg script. /usr/local/man/man1/listing.1 The man page, generated from Perl's POD. You can produce the manpage by typing 'pod2man listing >listing.1' BBBBUUUUGGGGSSSS lllliiiissssttttiiiinnnngggg has difficulties with very long source lines. Don't be bothered by overfull \hboxes. Most of the time, the result looks good, and if some (few) lines are cut off at the right margin, live with it or insert a linebreak. Certainly there are more bugs, since the Perl syntax is so hairy. But with reasonable sane source code, lllliiiissssttttiiiinnnngggg should do a good job. AAAAUUUUTTTTHHHHOOOORRRR Copyright 1998 by Chris Traxler . The GNU general public license applies. Special thanks go to Nicolas Le Clerc for working out a patch that uses Getopt::Long to simplify option handling. I also thank Vadim Belman for pointing out a bug, and Mathias Weber for useful hints regarding POD. You are permitted to use and alter lllliiiissssttttiiiinnnngggg under the terms of the GNU GPL. If you alter this file (and improve the program), I kindly ask you to send a copy to me at christoph.t.traxler@theo.physik.uni-giessen.de. You can retrieve a copy of the precise license terms at the URL ftp://prep.ai.mit.edu/pub/gnu/COPYING-2.0 lllliiiissssttttiiiinnnngggg can be retrieved from any CPAN mirror or from ftp://krabat.physik.uni-giessen.de/pub/traxler/ 4/Feb/98 perl 5.004 4