home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / unix / doc / indent.man < prev    next >
Text File  |  1993-06-13  |  16KB  |  463 lines
  1.  
  2.  
  3.  
  4. INDENT(1)                                               INDENT(1)
  5.  
  6.  
  7. NAME
  8.        indent - indent and format C program source
  9.  
  10. SYNOPSIS
  11.        indent   [  input-file  [ output-file ] ] [ -bad | -nbad ]
  12.               [ -bap | -nbap ]  [ -bbb | -nbbb ]   [ -bc | -nbc ]
  13.               [ -bl ]    [ -br ]    [ -brr ]   [ -cn ]   [ -cdn ]
  14.               [ -cdb | -ncdb ] [ -ce | -nce ] [ -cin ]  [ -clin ]
  15.               [ -ccin ] [ -dn ] [ -din ] [ -fc1 | -nfc1 ] [ -in ]
  16.               [ -ip | -nip ]  [ -ln ]   [ -lcn ]   [ -lp | -nlp ]
  17.               [ -pcs | -npcs ]     [ -npro ]     [ -prs | -nprs ]
  18.               [ -psl | -npsl ]  [ -sc | -nsc ]   [ -sob | -nsob ]
  19.               [ -st ] [ -tabsn ] [ -troff ] [ -v | -nv ] [ -+ ]
  20.  
  21.  
  22. DESCRIPTION
  23.        Indent  is a C program formatter.  It reformats the C pro-
  24.        gram in the input-file according  to  the  switches.   The
  25.        switches  which can be specified are described below. They
  26.        may appear before or after the file names.
  27.  
  28.        NOTE: If you only specify an input-file, the formatting is
  29.        done  'in-place',  that  is, the formatted file is written
  30.        back into input-file and a backup copy  of  input-file  is
  31.        written  in the current directory.  If input-file is named
  32.        '/blah/blah/file', the backup file is named file.BAK.
  33.  
  34.        If output-file is specified, indent checks to make sure it
  35.        is different from input-file.
  36.  
  37. OPTIONS
  38.        The  options  listed  below  control  the formatting style
  39.        imposed by indent.
  40.  
  41.        -bap,-nbap     If -bap  is  specified,  a  blank  line  is
  42.                       forced    after   every   procedure   body.
  43.                       Default: -nbap.
  44.  
  45.        -bad,-nbad     If -bad  is  specified,  a  blank  line  is
  46.                       forced  after  every block of declarations.
  47.                       Default: -nbad.
  48.  
  49.        -bbb,-nbbb     If -bbb  is  specified,  a  blank  line  is
  50.                       forced    before   every   block   comment.
  51.                       Default: -nbbb.
  52.  
  53.        -bc,-nbc       If -bc is  specified,  then  a  newline  is
  54.                       forced  after  each comma in a declaration.
  55.                       -nbc turns off this option.  The default is
  56.                       -bc.
  57.  
  58.        -br,-bl,-brr   Specifying -bl lines up compound statements
  59.  
  60.  
  61.  
  62.  
  63.  
  64.                           July 14, 1989                         1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. INDENT(1)                                               INDENT(1)
  71.  
  72.  
  73.                       like this:
  74.                           if (...)
  75.                           {
  76.                               code
  77.                           }
  78.                       Specifying -br  (the  default)  makes  them
  79.                       look like this:
  80.                           if (...) {
  81.                               code
  82.                           }
  83.                       And  specifying  -brr  makes them look like
  84.                       this:
  85.                           if (...)
  86.                               {
  87.                               code
  88.                               }
  89.  
  90.  
  91.        -cn            The column in which comments on code start.
  92.                       The default is 33.
  93.  
  94.        -cdn           The  column  in  which comments on declara-
  95.                       tions start.  The default is for these com-
  96.                       ments  to start in the same column as those
  97.                       on code.
  98.  
  99.        -cdb,-ncdb     Enables (disables) the placement of comment
  100.                       delimiters   on  blank  lines.   With  this
  101.                       option enabled, comments look like this:
  102.                            /*
  103.                             * this is a comment
  104.                             */
  105.                       Rather than like this:
  106.                            /* this is a comment */
  107.                       This only affects block comments, not  com-
  108.                       ments  to the right of code. The default is
  109.                       -cdb .
  110.  
  111.        -ce,-nce       Enables (disables) forcing 'else's to  cud-
  112.                       dle up to the immediatly preceeding -ce .
  113.  
  114.        -cin           Sets the continuation indent to be n.  Con-
  115.                       tinuation lines will be indented  that  far
  116.                       from the beginning of the first line of the
  117.                       statement.  Parenthesized expressions  have
  118.                       extra  indentation  added  to  indicate the
  119.                       nesting, unless  -lp  is  in  effect.   -ci
  120.                       defaults to the same value as -i.
  121.  
  122.        -clin          Causes  case  labels  to  be indented n tab
  123.                       stops to the right of the containing switch
  124.                       statement.   -cli0.5  causes case labels to
  125.                       be indented half a tab stop.   The  default
  126.                       is -cli0 .
  127.  
  128.  
  129.  
  130.                           July 14, 1989                         2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. INDENT(1)                                               INDENT(1)
  137.  
  138.  
  139.        -ccin          Causes case code to be indented n tab stops
  140.                       to the  right  of  the  corresponding  case
  141.                       label.   -cci0.5  causes  case  code  to be
  142.                       indented half a tab stop.  The  default  is
  143.                       -cci1 .
  144.  
  145.        -dn            Controls  the  placement  of comments which
  146.                       are not to the right of code.  The  default
  147.                       -d1 means that such comments are placed one
  148.                       indentation level  to  the  left  of  code.
  149.                       Specifying -d0 lines up these comments with
  150.                       the  code.   See  the  section  on  comment
  151.                       indentation below.
  152.  
  153.        -din           Specifies  the  indentation,  in  character
  154.                       positions, from a  declaration  keyword  to
  155.                       the  following  identifier.  The default is
  156.                       -di16 .
  157.  
  158.        -fc1,-nfc1     Enables (disables) the formatting  of  com-
  159.                       ments  that start in column 1.  Often, com-
  160.                       ments whose leading '/' is in column 1 have
  161.                       been  carefully  hand formatted by the pro-
  162.                       grammer.  In such cases,  -nfc1  should  be
  163.                       used.  The default is -fc1.
  164.  
  165.        -in            The  number  of  spaces for one indentation
  166.                       level.  The default is 4.
  167.  
  168.        -ip,-nip       Enables  (disables)  the   indentation   of
  169.                       parameter  declarations  from the left mar-
  170.                       gin.  The default is -ip .
  171.  
  172.        -ln            Maximum length  of  an  output  line.   The
  173.                       default is 75.
  174.  
  175.        -npro          Causes  the  profile files, './.indent.pro'
  176.                       and '~/.indent.pro', to be ignored.
  177.  
  178.        -lp,-nlp       Lines up code surrounded by parenthesis  in
  179.                       continuation  lines.   If a line has a left
  180.                       paren which is not  closed  on  that  line,
  181.                       then continuation lines will be lined up to
  182.                       start at the character position just  after
  183.                       the left paren.  For example, here is how a
  184.                       piece of continued code looks with -nlp  in
  185.                       effect:
  186.                           p1 = first_procedure(second_procedure(p2, p3),
  187.                               third_procedure(p4, p5));
  188.                       With  -lp  in effect (the default) the code
  189.                       looks somewhat clearer:
  190.                           p1 = first_procedure(second_procedure(p2, p3),
  191.                                                third_procedure(p4, p5));
  192.  
  193.  
  194.  
  195.  
  196.                           July 14, 1989                         3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. INDENT(1)                                               INDENT(1)
  203.  
  204.  
  205.                       Inserting a couple more newlines we get:
  206.                           p1 = first_procedure(second_procedure(p2,
  207.                                                                 p3),
  208.                                                third_procedure(p4,
  209.                                                                p5));
  210.  
  211.        -pcs , -npcs   If true (-pcs)  all  procedure  calls  will
  212.                       have  a space inserted between the name and
  213.                       the '('.  The default is -npcs
  214.  
  215.        -prs , -nprs   If true (-prs) all parentheses will have  a
  216.                       space inserted after the '(' and before the
  217.                       ')'.  The default is -nprs
  218.  
  219.        -psl , -npsl   If true  (-psl)  the  names  of  procedures
  220.                       being  defined  are  placed  in  column 1 -
  221.                       their types, if any, will be  left  on  the
  222.                       previous lines.  The default is -psl
  223.  
  224.        -sc,-nsc       Enables  (disables) the placement of aster-
  225.                       isks ('*'s) at the left edge  of  all  com-
  226.                       ments.
  227.  
  228.        -sob,-nsob     If  -sob  is specified, indent will swallow
  229.                       optional blank lines.  You can use this  to
  230.                       get  rid of blank lines after declarations.
  231.                       Default: -nsob
  232.  
  233.        -st            Causes indent to take its input from stdin,
  234.                       and put its output to stdout.
  235.  
  236.        -Ttypename     Adds typename to the list of type keywords.
  237.                       Names accumulate: -T can be specified  more
  238.                       than  once.   You  need  to specify all the
  239.                       typenames that appear in your program  that
  240.                       are  defined  by typedefs - nothing will be
  241.                       harmed if you miss a few, but  the  program
  242.                       won't  be formatted as nicely as it should.
  243.                       This sounds like a painful thing to have to
  244.                       do,  but it's really a symptom of a problem
  245.                       in C: typedef causes a syntactic change  in
  246.                       the  language  and  indent  can't  find all
  247.                       typedefs.
  248.  
  249.        -tabsn         Tells indent that tabs are assumed to be at
  250.                       every  n  columns.   The default is -tabs8.
  251.                       If n is less than 3 then tabs will  not  be
  252.                       used at all in the output.
  253.  
  254.        -troff         Causes  indent  to  format  the program for
  255.                       processing by troff.   It  will  produce  a
  256.                       fancy  listing  in  much the same spirit as
  257.                       vgrind.  If the output file is  not  speci-
  258.                       fied,   the  default  is  standard  output,
  259.  
  260.  
  261.  
  262.                           July 14, 1989                         4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. INDENT(1)                                               INDENT(1)
  269.  
  270.  
  271.                       rather than formatting in place.
  272.  
  273.        -v,-nv         -v turns on 'verbose' mode,  -nv  turns  it
  274.                       off.   When in verbose mode, indent reports
  275.                       when it splits one line of input  into  two
  276.                       or  more  lines  of  output, and gives some
  277.                       size statistics at completion. The  default
  278.                       is -nv.
  279.  
  280.        -+             turns  on  support for C++. In c++ mode, ::
  281.                       is permited in  identifiers,  C++  keywords
  282.                       are  supported,  and  class definition key-
  283.                       words (public, private, etc.)  are  set  in
  284.                       column 2.
  285.  
  286. FURTHER DESCRIPTION
  287.        You may set up your own 'profile' of defaults to indent by
  288.        creating a file called .indent.pro in  either  your  login
  289.        directory  or the current directory and including whatever
  290.        switches you like.  A '.indent.pro' in the current  direc-
  291.        tory  takes  precedence  over the one in your login direc-
  292.        tory.  If indent is run and a profile file exists, then it
  293.        is read to set up the program's defaults.  Switches on the
  294.        command line, though, always  override  profile  switches.
  295.        The  switches  should be separated by spaces, tabs or new-
  296.        lines.
  297.  
  298.        Comments
  299.  
  300.        'Box' comments.  Indent assumes that any  comment  with  a
  301.        dash  or star immediately after the start of comment (that
  302.        is, '/*-' or '/**') is a comment surrounded by  a  box  of
  303.        stars.   Each  line  of  such a comment is left unchanged,
  304.        except that its indentation may be adjusted to account for
  305.        the  change  in  indentation of the first line of the com-
  306.        ment.
  307.  
  308.        Straight text.  All other comments are treated as straight
  309.        text.   Indent  fits  as  many words (separated by blanks,
  310.        tabs, or newlines) on a line  as  possible.   Blank  lines
  311.        break paragraphs.
  312.  
  313.        Comment indentation
  314.  
  315.        If  a  comment is on a line with code it is started in the
  316.        'comment column', which is set by  the  -cn  command  line
  317.        parameter.   Otherwise, the comment is started at n inden-
  318.        tation levels less than  where  code  is  currently  being
  319.        placed,  where  n  is  specified  by  the -dn command line
  320.        parameter.  If the code on a line extends past the comment
  321.        column,  the  comment starts further to the right, and the
  322.        right margin may  be  automatically  extended  in  extreme
  323.        cases.
  324.  
  325.  
  326.  
  327.  
  328.                           July 14, 1989                         5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. INDENT(1)                                               INDENT(1)
  335.  
  336.  
  337.        Special Comments
  338.  
  339.        Indent  produces  and  interprets  some  special comments.
  340.        When indent cannot parse the source, it prints  a  message
  341.        on standard error and inserts a comment into the output of
  342.        the form
  343.             /**INDENT** ErrorMessage */
  344.  
  345.        Indent interprets several special comments as  directives.
  346.        First,  it makes no attempt to format lines containing the
  347.        error comment described above.
  348.  
  349.        Second, lines of the form:
  350.             /* INDENT OFF */
  351.        or
  352.             /* INDENT ON */
  353.        disable and re-enable indent formatting.   Any  amount  of
  354.        whitespace may replace the spaces shown in the examples.
  355.  
  356.        Third, indent allows formatting controls to be included in
  357.        the source via comments of the form:
  358.             /* INDENT: arg1 arg2 arg3 ... arg4 */
  359.        The arguments given are in the same syntax as the  command
  360.        line or profile file.  For example:
  361.             /* INDENT: -cli.25 -nfc1 */
  362.  
  363.        Preprocessor lines
  364.  
  365.        In  general,  indent leaves preprocessor lines alone.  The
  366.        only reformmatting that it will do  is  to  straighten  up
  367.        trailing  comments.   It  leaves  imbedded comments alone.
  368.        Conditional compilation  (#ifdef...#endif)  is  recognized
  369.        and  indent  attempts to correctly compensate for the syn-
  370.        tactic peculiarites introduced.
  371.  
  372.        C syntax
  373.  
  374.        Indent understands a substantial amount about  the  syntax
  375.        of  C,  but  it  has a 'forgiving' parser.  It attempts to
  376.        cope with the usual sorts of incomplete and misformed syn-
  377.        tax.  In particular, the use of macros like:
  378.                #define forever for(;;)
  379.        is handled properly.
  380.  
  381. FILES
  382.        ./.indent.pro  profile file
  383.  
  384. BUGS
  385.        Indent has even more switches than ls.
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                           July 14, 1989                         6
  395.  
  396.  
  397.  
  398.  
  399.  
  400. INDENT(1)                                               INDENT(1)
  401.  
  402.  
  403.        A common mistake that often causes grief is typing:
  404.            indent *.c
  405.        to the shell in an attempt to indent all the C programs in
  406.        a directory.  This is a really nasty thing to do.   (Think
  407.        about it.)
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.                           July 14, 1989                         7
  461.  
  462.  
  463.