home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 6 / FreshFish_September1994.bin / gnu / info / indent.info (.txt) < prev    next >
GNU Info File  |  1994-09-02  |  43KB  |  996 lines
  1. This is Info file indent.info, produced by Makeinfo-1.54 from the input
  2. file ./indent.texinfo.
  3.    Copyright (C) 1989, 1992, 1993, 1994 Free Software Foundation, Inc.
  4.    This is Edition 1.3, January, 1994, of `The `indent' Manual', for
  5. Indent Version 1.9
  6.    Permission is granted to make and distribute verbatim copies of this
  7. manual provided the copyright notice and this permission notice are
  8. preserved on all copies.
  9. File: indent.info,  Node: Top,  Next: Indent Program,  Prev: (dir),  Up: (dir)
  10. `indent':  Indent and Format C Program Source
  11. *********************************************
  12.    The `indent' program changes the appearance of a C program by
  13. inserting or deleting whitespace.
  14.    This is Edition 1.3, January 1994, of `The `indent' Manual', for
  15. Indent Version 1.9
  16. * Menu:
  17. * Indent Program::              The `indent' Program
  18. * Option Summary::              Option Summary
  19. * Index::                       Index
  20. File: indent.info,  Node: Indent Program,  Next: Option Summary,  Prev: Top,  Up: Top
  21. The `indent' Program
  22. ********************
  23.    The `indent' program can be used to make code easier to read.  It
  24. can also convert from one style of writing C to another.
  25.    `indent' understands a substantial amount about the syntax of C, but
  26. it also attempts to cope with incomplete and misformed syntax.
  27.    In version 1.2 and more recent versions, the GNU style of indenting
  28. is the default.
  29. * Menu:
  30. * Invoking indent::             Invoking `indent'
  31. * Backup files::                Backup Files
  32. * Common styles::               Common styles
  33. * Blank lines::                 Blank lines
  34. * Comments::                    Comments
  35. * Statements::                  Statements
  36. * Declarations::                Declarations
  37. * Indentation::                 Indentation
  38. * Disabling Formatting::        Disabling Formatting
  39. * Miscellaneous options::       Miscellaneous options
  40. * Bugs::                     Bugs
  41. * Copyright::                   Copyright
  42. File: indent.info,  Node: Invoking indent,  Next: Backup files,  Up: Indent Program
  43. Invoking `indent'
  44. =================
  45.    As of version 1.3, the format of the `indent' command is:
  46.      indent [OPTIONS] [INPUT-FILES]
  47.      
  48.      indent [OPTIONS] [SINGLE-INPUT-FILE] [-o OUTPUT-FILE]
  49.    This format is different from earlier versions and other versions of
  50. `indent'.
  51.    In the first form, one or more input files are specified.  `indent'
  52. makes a backup copy of each file, and the original file is replaced with
  53. its indented version.  *Note Backup files::, for an explanation of how
  54. backups are made.
  55.    In the second form, only one input file is specified.  In this case,
  56. or when the standard input is used, you may specify an output file after
  57. the `-o' option.
  58.    To cause `indent' to write to standard output, use the `-st' option.
  59. This is only allowed when there is only one input file, or when the
  60. standard input is used.
  61.    If no input files are named, the standard input is read for input.
  62. Also, if a filename named `-' is specified, then the standard input is
  63. read.
  64.    As an example, each of the following commands will input the program
  65. `slithy_toves.c' and write its indented text to `slithy_toves.out':
  66.      indent slithy_toves.c -o slithy_toves.out
  67.      
  68.      indent -st slithy_toves.c > slithy_toves.out
  69.      
  70.      cat slithy_toves.c | indent -o slithy_toves.out
  71.    Most other options to `indent' control how programs are formatted.
  72. As of version 1.2, `indent' also recognizes a long name for each option
  73. name.  Long options are prefixed by either `--' or `+'.(1) In most of
  74. this document, the traditional, short names are used for the sake of
  75. brevity.  *Note Option Summary::, for a list of options, including both
  76. long and short names.
  77.    Here is another example:
  78.      indent -br test/metabolism.c -l85
  79.    This will indent the program `test/metabolism.c' using the `-br' and
  80. `-l85' options, write the output back to `test/metabolism.c', and write
  81. the original contents of `test/metabolism.c' to a backup file in the
  82. directory `test'.
  83.    Equivalent invocations using long option names for this example would
  84.      indent --braces-on-if-line --line-length185 test/metabolism.c
  85.      
  86.      indent +braces-on-if-line +line-length185 test/metabolism.c
  87.    If you find that you often use `indent' with the same options, you
  88. may put those options into a file called `.indent.pro'.  `indent' will
  89. first look for `.indent.pro' in the current directory and use that if
  90. found.  Otherwise, `indent' will search your home directory for
  91. `.indent.pro' and use that file if it is found.  This behaviour is
  92. different from that of other versions of `indent', which load both
  93. files if they both exist.
  94.    Command line switches are handled *after* processing `.indent.pro'.
  95. Options specified later override arguments specified earlier, with one
  96. exception: Explicitly specified options always override background
  97. options (*note Common styles::.).  You can prevent `indent' from
  98. reading an `.indent.pro' file by specifying the `-npro' option.
  99.    ---------- Footnotes ----------
  100.    (1)   `+' is being superseded by `--' to maintain consistency with
  101. the POSIX standard.
  102. File: indent.info,  Node: Backup files,  Next: Common styles,  Prev: Invoking indent,  Up: Indent Program
  103. Backup Files
  104. ============
  105.    As of version 1.3, GNU `indent' makes GNU-style backup files, the
  106. same way GNU Emacs does.  This means that either "simple" or "numbered"
  107. backup filenames may be made.
  108.    Simple backup file names are generated by appending a suffix to the
  109. original file name.  The default for the this suffix is the
  110. one-character string `~' (tilde).  Thus, the backup file for `python.c'
  111. would be `python.c~'.
  112.    Instead of the default, you may specify any string as a suffix by
  113. setting the environment variable `SIMPLE_BACKUP_SUFFIX' to your
  114. preferred suffix.
  115.    Numbered backup versions of a file `momewraths' look like
  116. `momewraths.c.~23~', where 23 is the version of this particular backup.
  117. When making a numbered backup of the file `src/momewrath.c', the
  118. backup file will be named `src/momewrath.c.~V~', where V is one greater
  119. than the highest version currently existing in the directory `src'.
  120.    The type of backup file made is controlled by the value of the
  121. environment variable `VERSION_CONTROL'.  If it is the string `simple',
  122. then only simple backups will be made.  If its value is the string
  123. `numbered', then numbered backups will be made.  If its value is
  124. `numbered-existing', then numbered backups will be made if there
  125. *already exist* numbered backups for the file being indented;
  126. otherwise, a simple backup is made.  If `VERSION_CONTROL' is not set,
  127. then `indent' assumes the behaviour of `numbered-existing'.
  128.    Other versions of `indent' use the suffix `.BAK' in naming backup
  129. files.  This behaviour can be emulated by setting
  130. `SIMPLE_BACKUP_SUFFIX' to `.BAK'.
  131.    Note also that other versions of `indent' make backups in the
  132. current directory, rather than in the directory of the source file as
  133. GNU `indent' now does.
  134. File: indent.info,  Node: Common styles,  Next: Blank lines,  Prev: Backup files,  Up: Indent Program
  135. Common styles
  136. =============
  137.    There are several common styles of C code, including the GNU style,
  138. the Kernighan & Ritchie style, and the original Berkeley style.  A
  139. style may be selected with a single "background" option, which
  140. specifies a set of values for all other options.  However, explicitly
  141. specified options always override options implied by a background
  142. option.
  143.    As of version 1.2, the default style of GNU `indent' is the GNU
  144. style.  Thus, it is no longer neccessary to specify the option `-gnu'
  145. to obtain this format, although doing so will not cause an error.
  146. Option settings which correspond to the GNU style are:
  147.      -nbad -bap -nbc -bl -bli2 -c33 -cd33 -ncdb -nce -cli0
  148.      -cp1 -di2 -nfc1 -nfca -i2 -ip5 -lp -pcs -psl -cs
  149.      -nsc -nsob -nss -ts8 -d0 -ci0 -l78
  150.    The GNU coding style is that preferred by the GNU project.  It is the
  151. style that the GNU Emacs C mode encourages and which is used in the C
  152. portions of GNU Emacs.  (People interested in writing programs for
  153. Project GNU should get a copy of `The GNU Coding Standards', which also
  154. covers semantic and portability issues such as memory usage, the size
  155. of