Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1‎ > ‎

vgrind


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 embedded 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, formatted text goes to the standard out-
                     put.



     -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-deviceFormats 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    descrip-
                                             tions



     /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 pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments