unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

VGRIND(1)                   General Commands Manual                  VGRIND(1)



NAME
       vgrind - grind nice program listings

SYNOPSIS
       vgrind  [ -fntwWx ] [ -d defs-file ] [ -h header ] [ -llanguage ] [ -sn
       ] [ -opagelist ] [ -Pprinter ]
       [ -Toutput-device ] filename...

AVAILABILITY
       This command is available with the Text software  installation  option.
       Refer to for information on how to install optional software.

DESCRIPTION
       vgrind 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 margin.

       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 stan-
       dard 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.

       In  regular  mode  vgrind  accepts input filenames, processes them, and
       passes them to troff for output.  If no filename is given,  or  if  the
       `-' argument is given, vgrind reads from the standard input (default if
       -f is specified).

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

OPTIONS
       Note:  the syntax of options with arguments is important.  Some require
       a SPACE between the option name and the argument, while those  that  do
       not have a SPACE below will not tolerate one.

       -f     Force filter mode.

       -n     Do not make keywords boldface.

       -x     Output  the  index  file  in  a "pretty" format.  The index file
              itself is produced whenever vgrind is run  with  a  file  called
              index  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.

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

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

       -h header
              Specify a header to appear in the center of every output page.

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

       -sn    Specify 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 specified by the
       TROFF environment variable, see ENVIRONMENT below.

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

       -opagelist
              Print  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.

       -Pprinter
              Send output to the named printer.

       -Toutput-device
              Format output for the specified output-device.

       -W     Force output to the (wide)  Versatec  printer  rather  than  the
              (narrow) Varian.  vtroff(1) only.

ENVIRONMENT
       In  regular  mode vgrind feeds its intermediate output to the text for-
       matter given by the value of the  TROFF  environment  variable,  or  to
       troff  if this variable is not defined in the environment.  This mecha-
       nism 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

SEE ALSO
       troff(1), vtroff(1), 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  key-
                 words function or subroutine.

       MLisp     Function names should not appear on the same line as the pre-
                 ceding defun.

       Model     Function names need to appear on the same line  as  the  key-
                 words is beginproc.

       Pascal    Function  names  need  to appear on the same line as the key-
                 words function or procedure.

       If these conventions are not followed, the indexing and marginal  func-
       tion name comment mechanisms will fail.

       More  generally,  arbitrary  formatting styles for programs mostly look
       bad.  The use of SPACE characters to align source code fails miserably;
       if you plan to vgrind your program you should use TAB characters.  This
       is somewhat inevitable since the fonts vgrind uses are variable width.

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

       The -w option is a crock, 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  difficult  to  use  effec-
       tively.

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



                                  8 June 1988                        VGRIND(1)