home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / cpm68k / utils.lbr / INDENT.DQC / INDENT.DOC
Encoding:
Text File  |  1986-05-22  |  5.8 KB  |  143 lines
  1. indent - indent and format a C program source indent ifile [
  2. ofile ] [ args ] The arguments that can be specified follows.
  3. They may appear before or after the file names.
  4.  
  5. ifile Input file specification. 
  6.  
  7. ofile Output file specification.  If omitted, then the indented
  8. formatted file will be written back into the input file, and
  9. there will be a "back-up" copy of ifile written in the current
  10. directory. For an ifile named "/blah/blah/file", the backup file
  11. will be named ".Bfile". (It will only be listed when the `-a'
  12. argument is specified in ls.) If ofile is specified, indent
  13. checks to make sure it is different from ifile. 
  14.  
  15. -lnnn Maximum length of an output line. The default is 75.
  16.  
  17. -cnnn The column in which comments will start. The default is 33.
  18.  
  19. -cdnnn The column in which comments on declarations will start.
  20. The default is for these comments to start in the same column as
  21. other comments. 
  22.  
  23. -innn The number of spaces for one indentation level. The de-
  24. fault is 4.
  25.  
  26. -dj,-ndj -dj will cause declarations to be left justified. -ndj
  27. will cause them to be indented the same as code. The default is
  28. -ndj.
  29.  
  30. -v,-nv -v turns on "verbose" mode, -nv turns it off. When in ver-
  31. bose mode, indent will report when it splits one line of input
  32. into two or more lines of output, and it will give some size
  33. statistics at completion. The default is -nv.
  34.  
  35. -bc,-nbc If -bc is specified, then a newline will be forced
  36. after each comma in a declaration. -nbc will turn off this
  37. option. The default is -bc. 
  38.  
  39. -dnnn This option controls the placement of comments which are
  40. not to the right of code. Specifying -d2 means that such comments
  41. will be placed two indentation levels to the left of code. The
  42. default -d0 lines up these comments with the code. See the
  43. section on comment indentation below. 
  44.  
  45. -br,-bl Specifying -bl will cause complex statements to be lined
  46. up like this:
  47.  
  48.  if (...)
  49.  {
  50.  code
  51.  }
  52.  
  53. Specifying -br (the default) will make them look like this:
  54.  
  55.  if (...) {
  56.  code
  57.  }
  58.  
  59. You may set up your own `profile' of defaults to indent by
  60. creating the file `/usr/yourname/.indent.pro' (where your-name
  61. is your login name) and including whatever switches you like. If
  62. indent is run and a profile file exists, then it is read to set
  63. up the program's defaults. Switches on the command line, though,
  64. will always over-ride profile switches. The profile file must be
  65. a single line of not more than 127 characters. The switches
  66. should be seperated on the line by spaces or tabs.
  67.  
  68. Indent is intended primarily as a C program indenter.
  69. Specifically, indent will: indent code lines align comments
  70. insert spaces around operators where necessary break up
  71. declaration lists as in "int a,b,c;". It will not break up long
  72. statements to make them fit within the maximum line length, but
  73. it will flag lines that are too long. Lines will be broken so
  74. that each statement starts a new line, and braces will appear
  75. alone on a line. (See the -br option to inhibit this.) Also, an
  76. attempt is made to line up identifiers in declarations.
  77.  
  78. Multi-line expressions
  79.  
  80. Indent will not break up complicated expressions that extend over
  81. multiple lines, but it will usually correctly indent such
  82. expressions which have already been broken up. Such an expression
  83. might end up looking like this: 
  84.  
  85.  x =
  86.   (
  87.   (Arbitrary parenthesized expression)
  88.   +
  89.   (
  90.   (Parenthesized expression)
  91.   *
  92.   (Parenthesized expression)
  93.   )
  94.   );
  95.  
  96.  Comments
  97.  
  98. Indent recognizes four kinds of comments. They are straight
  99. text, "box" comments, UNIX-style comments, and comments that
  100. should be passed thru unchanged. The action taken with these
  101. various types is as follows:
  102.  
  103. "Box" comments: The DSG documentation standards specify that
  104. boxes will be placed around section headers. Indent assumes that
  105. any comment with a dash immediately after the start of comment
  106. (i.e. "/*-") is such a box. Each line of such a comment will be
  107. left unchanged, except that the first non-blank character of
  108. each successive line will be lined up with the beginning slash of
  109. the first line. Box comments will be indented (see below).
  110.  
  111. Unix-style comments: This is the type of section header which is
  112. used extensively in the UNIX system source. If the start of
  113. comment ('/*') appears on a line by itself, indent assumes that
  114. it is a UNIX-style comment. These will be treated similarly to
  115. box comments, except the first non-blank character on each line
  116. will be lined up with the '*' of the '/*'.
  117.  
  118. Unchanged comments: Any comment which starts in column 1 will be
  119. left completely unchanged. This is intended primarily for
  120. documentation header pages. The check for unchanged comments is
  121. made before the check for UNIX-style comments.
  122.  
  123. Straight text: All other comments are treated as straight text.
  124. Indent will fit as many words (separated by blanks, tabs, or
  125. newlines) on a line as possible. Straight text comments will be
  126. indented.
  127.  
  128. Comment indentation Box, UNIX-style, and straight text comments
  129. may be indented. If a comment is on a line with code it will be
  130. started in the "comment column", which is set by the -cnnn
  131. command line parameter. Otherwise, the comment will be started at
  132. nnn indentation levels less than where code is currently being
  133. placed, where nnn is specified by the -dnnn com- mand line
  134. parameter. (Indented comments will never be placed in column 1.)
  135. If the code on a line extends past the comment column, the
  136. comment will be moved to the next line.
  137.  
  138. Diagnostic error messsages, mostly to tell that a text line has
  139. been broken or is too long for the output line, will be printed
  140. on the controlling tty. /usr/your-name/.indent.pro - profile file
  141. Doesn't know how to format "long" declarations.
  142.  
  143.