vgrind(1)




NAME

     vgrind - grind nice program listings


SYNOPSIS

     vgrind [-2fntwx]  [-d defs-file]  [-h header]  [-l language]
     [-s n]    [-o pagelist]    [-P printer]   [-T output-device]
     filename...


DESCRIPTION

     The vgrind utility formats the program sources named by  the
     filename  arguments in a nice style using troff(1). Comments
     are placed in italics, keywords in bold face,  and  as  each
     function  is encountered its name is listed on the page mar-
     gin.

     vgrind runs in two basic modes, filter mode or regular mode.
     In  filter mode, vgrind acts as a filter in a manner similar
     to tbl(1). The standard input  is  passed  directly  to  the
     standard output except for lines bracketed by the troff-like
     macros:

      .vS  starts processing

     .vE   ends processing

     These lines are formatted as  described  above.  The  output
     from  this  filter  can be passed to troff for output. There
     need be no particular ordering with eqn(1) or tbl(1).

     In regular mode, vgrind accepts input  filenames,  processes
     them,  and  passes  them  to  troff for output. Use a hyphen
     (`-') to specify standard input; otherwise, vgrind will exit
     without   attempting   to  read  from  the  standard  input.
     Filenames must be specified after  all  other  option  argu-
     ments.

     In regular mode, if the -t or -P option  is  specified,  the
     output is:

        o  emitted (in troff format) to stdout if the  -t  option
           is specified.

        o  printed (as PostScript) to the named printer if the -P
           option is specified.

     Otherwise, the output is:

        o  printed (as PostScript) on the system default printer,
           if one is defined, and the command's stdout is a tty.

        o  emitted (as PostScript) to stdout if it is not  a  tty
           (that  is,  if  stdout  is  a  pipe or a redirect to a
           file).

     In both modes, vgrind passes  any  lines  beginning  with  a
     decimal point without conversion.


OPTIONS

     The following options are supported:

     - 2   Produces two-column  output.  Specifying  this  option
           changes  the  default  point  size to 8 (as if the -s8
           option were supplied). It also arranges for output  to
           appear in landscape mode.

     -f    Forces filter mode.

     -n    Does not make keywords boldface.

     -w    Considers <TAB> characters to be spaced  four  columns
           apart instead of the usual eight.

     -x    Outputs the index file in a "pretty" format. The index
           file  itself is produced whenever vgrind is run with a
           file called index  that  is  present  in  the  current
           directory.  The index of function definitions can then
           be run off by giving vgrind the -x option and the file
           index as argument.

     -d defs-file
           Specifies  an  alternate  language  definitions   file
           (default is /usr/lib/vgrindefs).

     -h header
           Specifies a header to appear in the  center  of  every
           output page. Use quotes to specify headers with embed-
           ded spaces.

     -l language
           Specifies the language to  use.  Among  the  languages
           currently  known are: Bourne shell (-lsh), C (-lc, the
           default), C++ (-lc++), C shell  (-lcsh),  emacs  MLisp
           (-lml),  FORTRAN  (-lf),  Icon (-lI), ISP (-i), LDL (-
           lLDL), Model (-lm), Pascal (-lp), and RATFOR (-lr).

     -P printer
           Sends output to the named printer.

     -s n  Specifies a point size to use on output  (exactly  the
           same  as  the  argument  of  a  troff  .ps  point size
           request).

     vgrind passes the following options to the formatter  speci-
     fied  by  the  TROFF  environment  variable. See ENVIRONMENT
     VARIABLES.

     - t   Similar to the same option in troff; that is,  format-
           ted text goes to the standard output.

     -o pagelist
           Prints only those pages whose page numbers  appear  in
           the comma-separated pagelist of numbers and ranges.  A
           range N-M means pages N through M; an initial -N means
           from  the  beginning  to  page N; and a final N- means
           from N to the end.

     -T output-device
           Formats output for the specified output-device.


OPERANDS

     The following operand is supported:

      filename
           Name of the program source to be processed by  vgrind.
           Use `-' to specify the standard input.


ENVIRONMENT VARIABLES

     In regular mode, vgrind feeds its intermediate output to the
     text  formatter  given by the value of the TROFF environment
     variable, or to  /usr/bin/troff  if  this  variable  is  not
     defined  in the environment. This mechanism allows for local
     variations in troff's name.


FILES

      index
           file where source for index is created

     /usr/lib/vgrindefs
           language descriptions

     /usr/lib/vfontedpr
           preprocessor

     /usr/share/lib/tmac/tmac.vgrind
           macro package


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWdoc                     |
    |_____________________________|_____________________________|


SEE ALSO

     csh(1), ctags(1), eqn(1), tbl(1),  troff(1),  attributes(5),
     vgrindefs(5)


BUGS

     vgrind assumes that a certain programming style is followed:

     C     Function names can be  preceded  on  a  line  only  by
           <SPACE>, <TAB>, or an asterisk (*).  The parenthesized
           arguments must also be on the same line.

     FORTRAN
           Function names need to appear on the same line as  the
           keywords function or subroutine.

     MLisp Function names should not appear on the same  line  as
           the preceding defun.

     Model Function names need to appear on the same line as  the
           keywords is beginproc.

     Pascal
           Function names need to appear on the same line as  the
           keywords function or procedure.

     If these conventions are not followed, the indexing and mar-
     ginal function name comment mechanisms will fail.

     More generally, arbitrary  formatting  styles  for  programs
     usually  give  unsightly  results.  To prepare a program for
     vgrind output, use <TAB> rather than <SPACE>  characters  to
     align source code properly, since vgrind uses variable width
     fonts.

     The mechanism of ctags(1) in recognizing functions should be
     used here.

     The -w option is annoying, but there  is  no  other  way  to
     achieve the desired effect.

     The macros defined in tmac.vgrind do not coexist  gracefully
     with  those of other macro packages, making filter mode dif-
     ficult to use effectively.

     vgrind does not process certain special characters in csh(1)
     scripts correctly.

     The tmac.vgrind formatting macros wire in  the  page  height
     and  width  used  in two-column mode, effectively making two
     column output useless for paper sizes other than  the  stan-
     dard  American  size  of  8.5 inches by 11 inches. For other
     paper sizes, it is necessary to edit the size  values  given
     in tmac.vgrind. A better solution would be to create a troff
     output  device  specification  intended   specifically   for
     landscape output and record size information there.


Man(1) output converted with man2html