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