home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / t / tex / !dvips / Documents / Fonts / Source / !lgrind / lg-docs / lgrind next >
Encoding:
Text File  |  1994-02-16  |  5.9 KB  |  185 lines
  1.  
  2. lgrind(1) USER COMMANDS lgrind(1)
  3.  
  4. NAME
  5.  lgrind - grind nice program listings using LaTeX
  6.  
  7. SYNOPSIS
  8.  lgrind [ -e ] [ -i ] [ - ] [ -n ] [ -h <header> ] [ -d <description file> ] [ -l<language> ] <name> ...
  9.  
  10. DESCRIPTION
  11.  Lgrind formats program sources in a nice style using (La)TeX(1). Comments are placed in roman,
  12.  key-words in bold face, variables in italics, and strings in typewriter font. Source file
  13.  line numbers appear in the right margin (every 10 lines).
  14.  
  15.  Lgrind processes its input file(s) and writes the result to standard output. This output can be saved for
  16.  later editting, inclusion in a larger document, etc.
  17.  
  18.  The options are:
  19.  
  20.  -e process a LaTeX file for embedded text.
  21.  
  22.  -i process for inclusion in a LaTeX document.
  23.  
  24.  - take input from standard input.
  25.  
  26.  -n don't boldface keywords.
  27.  
  28.  -h specifies text to go on the left side of every output page (default is none).
  29.  
  30.  -d specifies the language definitions file (default is /cs/lib/lgrindefs).
  31.  
  32.  -l specifies the language to use. Currently known are
  33.  
  34.  C (-lc or the default),
  35.  C++ (-lc++ or-lCC),
  36.  PASCAL (-lp),
  37.  Modula-2 (-lm2),
  38.  Fortran (-lf),
  39.  RATFOR (-lr),
  40.  Yacc (-ly),
  41.  PostScript (-lps),
  42.  Prolog (-lprolog),
  43.  MLisp (-lmlisp),
  44.  Icon (-lI),
  45.  TeX (-ltex),
  46.  Metafont (-lmf),
  47.  Perl (-lperl),
  48.  CSH (-lcsh),
  49.  Bourne Shell (-lsh)
  50.  assembler (-lasm),
  51.  68000 assembler (-la68),
  52.  asm68 (-lasm68),
  53.  VMS assembler (-lvmsasm),
  54.  ISP (-lisp),
  55.  LDL (-lldl),
  56.  Linda (-llinda),
  57.  MODEL(-lm),
  58.  and Russell (-lrussell).
  59.  
  60.  If neither -e nor -i are specified, a complete LaTeX file is produced.
  61.  
  62. USAGE
  63.  For example, to include a C file named foo.c into your LaTeX document, first give the command:
  64.  
  65.  lgrind -i -lc foo.c > foo.tex
  66.  
  67.  This will generate foo.tex, which will have the pretty-printed version of foo.c with a lot of
  68.  LaTeX commands.
  69.  
  70.  Then include lgrind.sty as you include any other style, namely with the
  71.   ocumentstyle[...,lgrind,...]{...} line at the beginning of your LaTeX document.
  72.  Having done this, within the document you can include foo.tex using one of the following
  73.  commands:
  74.  
  75.  
  76.  which will simply include the file at that point of text, and will draw horizontal lines
  77.  before and after the listing.
  78.  
  79.  ption}{label}
  80.  which will put the listing also within a figure environment, using the float options,
  81.  caption and label you gave.
  82.  
  83.  To produce a standalone LaTeX file from, say, a Yacc file:
  84.  
  85.  lgrind bary.y > bary.tex
  86.  This uses Piet van Oostrum's fancyheadings.sty to make the headers and footers.
  87.  
  88.  For a more detailed explanation of these commands, refer to /cs/lib/tex/inputs/lgrind.doc.
  89.  
  90. EMBEDDED PROGRAMS WITHIN A LaTeX FILE
  91.  (From Jerry Leichter's notes.)
  92.  
  93.  
  94.  
  95. Sun Release 4.1 Last change: 1
  96.  
  97.  
  98. lgrind(1) USER COMMANDS lgrind(1)
  99.  
  100.  Within the text of your LaTeX file, you mark groups of lines as either text- or display-style
  101.  program code:
  102.  
  103.  Text style: l l. The expression %( a + 3 %) produces 10.
  104.  prints something like: "The expression a + 3 produces 10." (with "a + 3" set as a program.)
  105.  
  106.  The same effect can be achieved with inline @'s. l l. The expression @a + 3@ produces 10.
  107.  
  108.  Display style: l l. The statement %[ a += 3; %] is an exam-
  109.  ple of an incrementing operator. prints something like: l l. The statement a +=
  110.  3; is an example of an incrementing operator.
  111.  
  112.  Important rules:
  113.  
  114.  % and the following character must be the first two characters on the line to be recognized.
  115.  
  116.  Put nothing on the line after the % and the key character. If you do that, lgrind will provide a
  117.  default environment that will produce an x for %( )%, and a x for %[ - %]. If you put
  118.  stuff on the line, lgrind assumes you want to control the format completely. Doing this
  119.  requires understanding exactly what the code lgrind produces is doing. (Sometimes I'm not
  120.  sure I do!)
  121.  
  122.  %) and %] are, if I remember right, simply ignored outside of a code group, but any extra %(
  123.  or %[ produces a warning, so a missing %) or %] is usually caught.
  124.  
  125.  You can insert your own code by using a line starting with %= in the program text. Whatever you
  126.  enter after that is left in the output, exactly as you typed it. It will be executed in a strange environ-
  127.  ment, so doing anything fancy is very tricky. A macro, s provided to help you do simple things.
  128.  For example, tab (/); l. %[ %=
  129.  a = 1; %] produces: tab (/); l.
  130.  .
  131.  .
  132.  .
  133.  a = 1;
  134.  
  135.  (Within the program text, _ is active and expands to a fixed-width space. A whole bunch of
  136.  macros are also defined. If you understand how lgrind sets lines up, you can replace the
  137.  8 _'s with a call to Tab \(em but I'll let you hang yourself on that one.)
  138.  
  139.  The output of lgrind always contains exactly one output line for each input line. Hence,
  140.  you can look up line numbers in TeX error messages in your original file, rather than in the
  141.  lgrind'ed (lground?) file. (Of course, if the problem is in the lgrind output....)
  142.  
  143.  Many things are controllable by re-defining various macros. You can change what fonts lgrind
  144.  will use for various kinds of things, how much it indents the output, whether it adds line
  145.  numbers, and if so at what interval it prints them and whether it sticks them on the left or
  146.  right, and so on. This stuff is all described in lgrind.doc, though probably not very well.
  147.  The default settings produce output that looks reasonable to me, though I can't say I'm
  148.  ecstatic about it. Doing a really good job would require defining some special fonts.
  149.  
  150. FILES
  151.  /cs/bin/lgrind
  152.  Executable
  153.  
  154.  /cs/lib/tex/inputs/lgrind.doc
  155.  Documented LaTeX style file
  156.  
  157.  /cs/lib/tex/inputs/lgrind.sty
  158.  LaTeX style file
  159.  
  160.  /cs/lib/lgrindefs
  161.  Language descriptions
  162.  
  163.  
  164. Sun Release 4.1 Last change: 2
  165.  
  166.  
  167. lgrind(1) USER COMMANDS lgrind(1)
  168.  
  169. AUTHOR
  170.  Van Jacobson, Lawrence Berkeley Laboratory (based on "vgrind" by Dave Presotto & William Joy of
  171.  UC Berkeley), wrote it for TeX.
  172.  
  173.  Jerry Leichter of Yale University modified it for LaTeX.
  174.  
  175.  George V. Reilly of Brown University changed the name to lgrind, fixed up the man page, and added
  176.  the program-text-within-comments and @-within-LaTeX features.
  177.  
  178. SEE ALSO
  179.  latex(1), tex(1), vgrind(1), lgrindefs(5)
  180.  
  181.  
  182. Sun Release 4.1 Last change: 3
  183.  
  184.  
  185.