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