packages icon



 lgrind(1)                                                         lgrind(1)




 NAME
      lgrind - grind nice program listings using LaTeX

 SYNOPSIS
      lgrind [ -e ] [ -i ] [ - ] [ -n ] [ -h <header> ] [ -d <description
      file> ] [ -l<language> ] <name> ...

 DESCRIPTION
      Lgrind formats program sources in a nice style using (La)TeX(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 editting, inclusion in a
      larger document, etc.

      The options are:

      -e   process a LaTeX file for embedded text.

      -i   process for inclusion in a LaTeX document.

      -    take input from standard input.

      -n   don't boldface keywords.

      -h   specifies text to go on the left side of every output page
           (default is none).

      -d   specifies the language definitions file (default is
           /cs/lib/lgrindefs).

      -l   specifies the language to use.  Currently known are C (-lc or the
           default), C++ (-lc++ or -lCC), PASCAL (-lp), Modula-2 (-lm2),
           Fortran (-lf), RATFOR (-lr), Yacc (-ly), PostScript (-lps),
           Prolog (-lprolog), MLisp (-lmlisp), Icon (-lI), TeX (-ltex),
           Metafont (-lmf), Perl (-lperl), CSH (-lcsh), Bourne Shell (-lsh)
           assembler (-lasm), 68000 assembler (-la68), asm68 (-lasm68), VMS
           assembler (-lvmsasm), ISP (-lisp), LDL (-lldl), Linda (-llinda),
           MODEL (-lm), and Russell (-lrussell).

      If neither -e nor -i are specified, a complete LaTeX file is produced.

 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





                                    - 1 -          Formatted:  June 30, 2022






 lgrind(1)                                                         lgrind(1)




      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 \documentstyle[...,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 bary.y > bary.tex
           This uses Piet van Oostrum's fancyheadings.sty to make the
           headers and footers.

      For a more detailed explanation of these commands, refer to
      /cs/lib/tex/inputs/lgrind.doc.

 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: l l.       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.  l l.       The
      expression @a + 3@ produces 10.

      Display style: l l.       The statement      %[      a += 3;      %]
           is an example of an incrementing operator.  prints something
      like: l l.       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



                                    - 2 -          Formatted:  June 30, 2022






 lgrind(1)                                                         lgrind(1)




           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, tab (/); l.
      %[ %=\Line{________\vdots}
              a = 1; %] produces: tab (/); l.
              .
              .
              .
              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.doc, 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
      /cs/bin/lgrind
           Executable

      /cs/lib/tex/inputs/lgrind.doc
           Documented LaTeX style file

      /cs/lib/tex/inputs/lgrind.sty
           LaTeX style file

      /cs/lib/lgrindefs
           Language descriptions



                                    - 3 -          Formatted:  June 30, 2022






 lgrind(1)                                                         lgrind(1)




 AUTHOR
      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.

 SEE ALSO
      latex(1), tex(1), vgrind(1), lgrindefs(5)










































                                    - 4 -          Formatted:  June 30, 2022