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