home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Archive / OS2_Archive_CD-ROM_Walnut_Creek_May_1992.iso / novell / progrmng / indent.zoo / indent.man < prev    next >
Text File  |  1989-05-24  |  11KB  |  282 lines
  1. INDENT(1)          USER COMMANDS            INDENT(1)
  2.  
  3.  
  4.  
  5. NAME
  6.      indent - indent and format    C program source
  7.  
  8. SYNOPSIS
  9.      indent  [ input-file  [  output-file  ]  ]     [ -bad    | -nbad    ]
  10.         [ -bap | -nbap ]    [ -bbb | -nbbb ]   [ -bc | -nbc    ]
  11.         [ -bl ]  [ -br ]  [    -cn ]  [ -cdn ]     [ -cdb    | -ncdb    ]
  12.         [ -ce | -nce ]  [ -cin ]  [    -clin ]     [ -dn ] [ -din    ]
  13.         [ -fc1 | -nfc1 ]   [ -in ]     [ -ip | -nip ]      [ -ln    ]
  14.         [ -lcn ]  [    -lp | -nlp ]  [    -pcs | -npcs ]    [ -npro    ]
  15.         [ -psl | -npsl ]   [ -sc | -nsc ]     [ -sob    | -nsob    ]
  16.         [ -st ] [ -tabsn ] [ -troff    ] [ -v | -nv ]
  17.  
  18. DESCRIPTION
  19.      Indent is a C program formatter.  It reformats the    C program
  20.      in     the  input-file according to the switches.  The switches
  21.      which can be specified are    described below. They may  appear
  22.      before or after the file names.
  23.  
  24.      NOTE: If you only specify an input-file, the  formatting  is
  25.      done `in-place', that is, the formatted file is written back
  26.      into input-file and a backup copy of input-file  is  written
  27.      in      the    current      directory.    If  input-file    is  named
  28.      `/blah/blah/file',    the backup file    is named file.BAK.
  29.  
  30.      If    output-file is specified, indent checks    to make     sure  it
  31.      is    different from input-file.
  32.  
  33. OPTIONS
  34.      The  options  listed  below  control  the    formatting  style
  35.      imposed by    indent.
  36.  
  37.      -bap,-nbap        If -bap is specified, a blank line is  forced
  38.             after every    procedure body.     Default: -nbap.
  39.  
  40.      -bad,-nbad        If -bad is specified, a blank line is  forced
  41.             after  every block of declarations.     Default:
  42.             -nbad.
  43.  
  44.      -bbb,-nbbb        If -bbb is specified, a blank line is  forced
  45.             before every block comment.     Default: -nbbb.
  46.  
  47.      -bc,-nbc        If -bc is specified, then a    newline    is forced
  48.             after each comma in    a declaration. -nbc turns
  49.             off    this option.  The default is -bc.
  50.  
  51.      -br,-bl        Specifying -bl lines up  compound  statements
  52.             like this:
  53.             if (...)
  54.             {
  55.                 code
  56.             }
  57.  
  58. INDENT(1)          USER COMMANDS            INDENT(1)
  59.  
  60.  
  61.  
  62.             Specifying -br (the    default) makes them  look
  63.             like this:
  64.             if (...) {
  65.                 code
  66.             }
  67.  
  68.      -cn        The    column in which    comments on  code  start.
  69.             The    default    is 33.
  70.  
  71.      -cdn        The    column in which    comments on  declarations
  72.             start.   The default is for    these comments to
  73.             start in the same column as    those on code.
  74.  
  75.      -cdb,-ncdb        Enables (disables) the placement  of  comment
  76.             delimiters    on blank lines.     With this option
  77.             enabled, comments look like    this:
  78.              /*
  79.               * this is a comment
  80.               */
  81.             Rather than    like this:
  82.              /* this is a comment */
  83.             This only affects block  comments,    not  com-
  84.             ments  to  the  right of code. The default is
  85.             -cdb .
  86.  
  87.      -ce,-nce        Enables (disables) forcing `else's to  cuddle
  88.             up    to  the     immediatly  preceeding    `}'.  The
  89.             default is -ce .
  90.  
  91.      -cin        Sets the continuation indent to be    n.   Con-
  92.             tinuation  lines  will  be    indented that far
  93.             from the beginning of the first line  of  the
  94.             statement.     Parenthesized    expressions  have
  95.             extra indentation added to indicate    the nest-
  96.             ing,  unless  -lp is in effect.  -ci defaults
  97.             to the same    value as -i.
  98.  
  99.      -clin        Causes case    labels to be indented n    tab stops
  100.             to    the right of the containing switch state-
  101.             ment.   -cli0.5  causes  case  labels  to  be
  102.             indented  half  a  tab  stop.  The default is
  103.             -cli0 .
  104.  
  105.      -dn        Controls the placement of comments which  are
  106.             not     to  the  right    of code.  The default -d1
  107.             means  that     such  comments     are  placed  one
  108.             indentation      level     to  the  left    of  code.
  109.             Specifying -d0 lines up these  comments  with
  110.             the     code.    See the    section    on comment inden-
  111.             tation below.
  112.  
  113.      -din        Specifies  the  indentation,   in    character
  114.  
  115. INDENT(1)          USER COMMANDS            INDENT(1)
  116.  
  117.  
  118.  
  119.             positions,    from a declaration keyword to the
  120.             following identifier.  The default is -di16    .
  121.  
  122.      -fc1,-nfc1        Enables (disables) the formatting of comments
  123.             that  start     in  column  1.      Often, comments
  124.             whose leading `/' is in column  1  have  been
  125.             carefully  hand  formatted by the programmer.
  126.             In such cases, -nfc1  should  be  used.   The
  127.             default is -fc1.
  128.  
  129.      -in        The    number    of  spaces  for     one  indentation
  130.             level.  The    default    is 4.
  131.  
  132.      -ip,-nip        Enables (disables) the indentation of parame-
  133.             ter     declarations  from the    left margin.  The
  134.             default is -ip .
  135.  
  136.      -ln        Maximum  length  of     an  output  line.    The
  137.             default is 75.
  138.  
  139.      -npro        Causes the profile files, `./.indent.pro' and
  140.             `~/.indent.pro', to    be ignored.
  141.  
  142.      -lp,-nlp        Lines up code surrounded  by  parenthesis  in
  143.             continuation  lines.   If  a  line has a left
  144.             paren which    is not closed on that line,  then
  145.             continuation  lines    will be    lined up to start
  146.             at the character position just after the left
  147.             paren.   For  example, here    is how a piece of
  148.             continued code looks with -nlp in effect:
  149.             p1 = first_procedure(second_procedure(p2, p3),
  150.                 third_procedure(p4,    p5));
  151.             With -lp in    effect    (the  default)    the  code
  152.             looks somewhat clearer:
  153.             p1 = first_procedure(second_procedure(p2, p3),
  154.                          third_procedure(p4, p5));
  155.             Inserting a    couple more newlines we    get:
  156.             p1 = first_procedure(second_procedure(p2,
  157.                                   p3),
  158.                          third_procedure(p4,
  159.                                  p5));
  160.  
  161.      -pcs , -npcs   If true (-pcs) all procedure calls will  have
  162.             a  space  inserted    between     the name and the
  163.             '('.  The default is -npcs
  164.  
  165.      -psl , -npsl   If true (-psl) the names of    procedures  being
  166.             defined are    placed in column 1 - their types,
  167.             if any, will be left on the     previous  lines.
  168.             The    default    is -psl
  169.  
  170.      -sc,-nsc        Enables (disables) the placement of    asterisks
  171.  
  172. INDENT(1)          USER COMMANDS            INDENT(1)
  173.  
  174.  
  175.  
  176.             (`*'s) at the left edge of all comments.
  177.  
  178.      -sob,-nsob        If -sob is    specified,  indent  will  swallow
  179.             optional  blank  lines.   You can use this to
  180.             get    rid of blank  lines  after  declarations.
  181.             Default: -nsob
  182.  
  183.      -st        Causes indent to take its input  from  stdin,
  184.             and    put its    output to stdout.
  185.  
  186.      -Ttypename        Adds typename to the list of  type    keywords.
  187.             Names  accumulate:    -T  can    be specified more
  188.             than once.     You  need  to    specify     all  the
  189.             typenames  that  appear  in    your program that
  190.             are    defined    by typedefs  -    nothing     will  be
  191.             harmed  if    you  miss  a few, but the program
  192.             won't be formatted as nicely  as  it  should.
  193.             This  sounds  like a painful thing to have to
  194.             do,    but it's really    a symptom of a problem in
  195.             C:    typedef     causes    a syntactic change in the
  196.             laguage and    indent can't find all typedefs.
  197.  
  198.      -tabsn        Tells indent that tabs are to be  aligned  at
  199.             every n columns.  The default is -tabs8.
  200.  
  201.      -troff        Causes indent to format the    program    for  pro-
  202.             cessing  by     troff.      It will produce a fancy
  203.             listing in much the    same  spirit  as  vgrind.
  204.             If    the  output  file  is  not specified, the
  205.             default is standard    output,    rather than  for-
  206.             matting in place.
  207.  
  208.      -v,-nv        -v turns on    `verbose' mode,    -nv turns it off.
  209.             When  in verbose mode, indent reports when it
  210.             splits one line of input  into  two     or  more
  211.             lines  of output, and gives    some size statis-
  212.             tics at completion.    The default is -nv.
  213.  
  214. FURTHER    DESCRIPTION
  215.      You may set up your own `profile' of defaults to  indent  by
  216.      creating  a  file    called    .indent.pro  in    either your login
  217.      directory or the current directory     and  including     whatever
  218.      switches you like.     A `.indent.pro' in the    current    directory
  219.      takes precedence over the one in your login  directory.   If
  220.      indent  is    run and    a profile file exists, then it is read to
  221.      set up the    program's  defaults.   Switches     on  the  command
  222.      line,   though,   always  override     profile  switches.   The
  223.      switches should be    separated by spaces, tabs or newlines.
  224.  
  225. INDENT(1)          USER COMMANDS            INDENT(1)
  226.  
  227.  
  228.      Comments
  229.  
  230.      `Box' comments.  Indent assumes that any comment with a dash
  231.      or     star  immediately  after  the start of    comment    (that is,
  232.      `/*-' or `/**') is    a comment surrounded by    a box  of  stars.
  233.      Each  line     of such a comment is left unchanged, except that
  234.      its indentation may be adjusted to    account    for the    change in
  235.      indentation of the    first line of the comment.
  236.  
  237.      Straight text.  All other comments    are treated  as     straight
  238.      text.  Indent fits    as many    words (separated by blanks, tabs,
  239.      or    newlines) on a line as possible.  Blank    lines break para-
  240.      graphs.
  241.  
  242.      Comment indentation
  243.  
  244.      If    a comment is on    a line with code it  is     started  in  the
  245.      `comment  column',     which    is  set     by  the -cn command line
  246.      parameter.     Otherwise, the    comment    is started at n     indenta-
  247.      tion  levels less than where code is currently being placed,
  248.      where n is    specified by the -dn command line parameter.   If
  249.      the code on a line    extends    past the comment column, the com-
  250.      ment starts further to the    right, and the right  margin  may
  251.      be    automatically extended in extreme cases.
  252.  
  253.      Preprocessor lines
  254.  
  255.      In    general, indent    leaves    preprocessor  lines  alone.   The
  256.      only  reformmatting  that    it  will  do  is to straighten up
  257.      trailing comments.     It leaves imbedded comments alone.  Con-
  258.      ditional  compilation  (#ifdef...#endif)  is  recognized and
  259.      indent attempts to    correctly compensate  for  the    syntactic
  260.      peculiarites introduced.
  261.  
  262.      C syntax
  263.  
  264.      Indent understands    a substantial amount about the syntax  of
  265.      C,     but  it  has  a `forgiving' parser.  It attempts to cope
  266.      with the usual sorts of incomplete    and misformed syntax.  In
  267.      particular, the use of macros like:
  268.          #define forever for(;;)
  269.      is    handled    properly.
  270.  
  271. FILES
  272.      ./.indent.pro  profile file
  273.  
  274. BUGS
  275.      Indent has    even more switches than    ls.
  276.  
  277.      A common mistake that often causes    grief is typing:
  278.      indent    *.c
  279.      to    the shell in an    attempt    to indent all the C programs in    a
  280.      directory.     This is probably a bug, not a feature.
  281.  
  282.