Provided by: lgrind_3.67-6_amd64 bug

NAME

       lgrind - grind nice program listings using LaTeX

NOTE

       This  man page is not yet much outdated, but might be soon except somebody asks me to work
       on it. Consider the LaTeX docs the real docs.

SYNOPSIS

       lgrind [ -e ] [ -i ] [ - ] [ -n ] [ -c ] [ -t <width> ] [ -h <header> ] [ -d  <description
       file> ] [ -l<language> ] [ -s ] <name> ...

DESCRIPTION

       LGrind  formats  program  sources  in a nice style using LaTeX(1).  Comments are placed in
       roman, keywords in bold face, variables in italics, and strings in typewriter font. Source
       file line numbers appear in the right margin (every 10 lines).

       LGrind  processes its input file(s) and writes the result to standard output.  This output
       can be saved for later editing, inclusion in a larger document, etc.

       The options are:

       -e     process a LaTeX file for embedded code.

       -i     process source code file for inclusion in a LaTeX document.

       -      take input from standard input.

       -n     don't boldface keywords.

       -c     don't treat @, etc. specially in comments.

       -t     change tab width (default 8).

       -h     specifies text to go into the header.

       -d     specifies      the      language      definitions      file       (default       is
              /usr/lib/texmf/tex/latex/lgrind/lgrindef).

       -d!    same as above, but write patched executable.

       -l     specifies the language to use.

       -s     shows a list of currently known languages.

       If LGrind is called without parameters, a help screen will be shown.  If neither -e nor -i
       are specified, a complete LaTeX file is produced. When no language  is  specified,  LGrind
       tries to find out the language used itself; C is used when this fails.

USAGE

       For  example,  to  include  a  C file named foo.c into your LaTeX document, first give the
       command:

           lgrind -i -lc foo.c > foo.tex

       This will generate foo.tex, which will have the pretty-printed version of foo.c with a lot
       of LaTeX commands.

       Then   include   lgrind.sty   as   you   include   any   other   style,  namely  with  the
       \usepackage{lgrind} line at the beginning of your LaTeX document. Having done this, within
       the document you can include foo.tex using one of the following commands:

       \lgrindfile{foo.tex}
              which  will simply include the file at that point of text, and will draw horizontal
              lines before and after the listing.

       \lagrind[htbp]{foo.tex}{caption}{label}
              which will put the listing also  within  a  figure  environment,  using  the  float
              options, caption and label you gave.

       To produce a standalone LaTeX file from, say, a Yacc file:

           lgrind -ly bary.y > bary.tex
              This uses Piet van Oostrum's fancyhdr.sty to make the headers and footers.

       For     a     more     detailed     explanation    of    these    commands,    refer    to
       /usr/TeX/texmf/doc/latex/lgrind.dvi.

EMBEDDED PROGRAMS WITHIN A LaTeX FILE

       (From Jerry Leichter's notes.)

       Within the text of your LaTeX file, you mark groups of lines as either text-  or  display-
       style program code:

       Text style:

           The expression
           %(
           a + 3
           %)
           produces 10.
       prints  something  like:   "The  expression  a  +  3 produces 10."  (with "a + 3" set as a
       program.)

       The same effect can be achieved with inline @'s.

           The expression @a + 3@ produces 10.

       Display style:

           The statement
           %[
           a += 3;
           %]
           is an example of an incrementing operator.
       prints something like:

           The statement
                 a += 3;
           is an example of an incrementing operator.

       Important rules:

              % and the following character must be the first two characters on the  line  to  be
              recognized.

              Put  nothing on the line after the % and the key character.  If you do that, LGrind
              will provide a default environment that will produce an \hbox  for  %(  )%,  and  a
              \vbox  for  %[  -  %].   If  you  put stuff on the line, LGrind assumes you want to
              control the format completely.  Doing this requires understanding exactly what  the
              code LGrind produces is doing. (Sometimes I'm not sure I do!)

              %) and %] are, if I remember right, simply ignored outside of a code group, but any
              extra %( or %[ produces a warning, so a missing %) or %] is usually caught.

       You can insert your own code by using a  line  starting  with  %=  in  the  program  text.
       Whatever  you enter after that is left in the output, exactly as you typed it.  It will be
       executed in a strange environment, so doing anything  fancy  is  very  tricky.   A  macro,
       \Line, is provided to help you do simple things.  For example,

       %[
       %=\Line{________\vdots}

               a = 1;
       %]
       produces:

               .
               .
               .
               a = 1;

       (Within  the  program text, _ is active and expands to a fixed-width space.  A whole bunch
       of macros are also defined.  If you understand how LGrind sets lines up, you  can  replace
       the 8 _'s with a call to \Tab — but I'll let you hang yourself on that one.)

       The  output of LGrind always contains exactly one output line for each input line.  Hence,
       you can look up line numbers in TeX error messages in your original file, rather  than  in
       the lgrind'ed (lground?) file.  (Of course, if the problem is in the LGrind output....)

       Many  things  are  controllable  by re-defining various macros.  You can change what fonts
       LGrind will use for various kinds of things, how much it indents the  output,  whether  it
       adds line numbers, and if so at what interval it prints them and whether it sticks them on
       the left or right, and so on.  This stuff is all described in lgrind.dvi, though  probably
       not  very  well. The default settings produce output that looks reasonable to me, though I
       can't say I'm ecstatic about it.  Doing a really good  job  would  require  defining  some
       special fonts.

FILES

       /usr/bin/lgrind
              Executable

       /usr/share/doc/lgrind/lgrind.dvi.gz
              Documentation

       /usr/share/texmf/tex/latex/lgrind/lgrind.sty
              LaTeX style file

       /usr/share/texmf/tex/latex/lgrind/lgrindef
              Language descriptions

AUTHORS

       Van  Jacobson,  Lawrence Berkeley Laboratory (based on "vgrind" by Dave Presotto & William
       Joy of UC Berkeley), wrote it for TeX.

       Jerry Leichter of Yale University modified it for LaTeX.

       George V. Reilly of Brown University changed the name to lgrind, fixed up  the  man  page,
       and added the program-text-within-comments and @-within-LaTeX features.

       Michael  Piefel  of  Humboldt-University  Berlin  adapted  it  to LaTeX2e and wrote decent
       documentation.

SEE ALSO

       latex(1), tex(1), vgrind(1), lgrindef(5)