Return to indent.1 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / pgrm / indent

Annotation of 43BSDReno/pgrm/indent/indent.1, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1980, 1990 The Regents of the University of California.
        !             2: .\" Copyright (c) 1985 Sun Microsystems, Inc.
        !             3: .\" Copyright (c) 1976 Board of Trustees of the University of Illinois.
        !             4: .\" All rights reserved.
        !             5: .\"
        !             6: .\" Redistribution and use in source and binary forms are permitted provided
        !             7: .\" that: (1) source distributions retain this entire copyright notice and
        !             8: .\" comment, and (2) distributions including binaries display the following
        !             9: .\" acknowledgement:  ``This product includes software developed by the
        !            10: .\" University of California, Berkeley and its contributors'' in the
        !            11: .\" documentation or other materials provided with the distribution and in
        !            12: .\" all advertising materials mentioning features or use of this software.
        !            13: .\" Neither the name of the University nor the names of its contributors may
        !            14: .\" be used to endorse or promote products derived from this software without
        !            15: .\" specific prior written permission.
        !            16: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
        !            17: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
        !            18: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            19: .\"
        !            20: .\"     @(#)indent.1   6.8 (Berkeley) 7/24/90
        !            21: .\"
        !            22: .Dd July 24, 1990
        !            23: .Dt INDENT 1
        !            24: .Sh NAME
        !            25: .Nm indent
        !            26: .Nd indent and format C program source
        !            27: .Sh SYNOPSIS
        !            28: .Nm indent
        !            29: .Op Ar input-file Op Ar output-file
        !            30: .Cx \&[
        !            31: .Fl bad
        !            32: .Cx \&\ |\ \&
        !            33: .Fl nbad
        !            34: .Cx \&]
        !            35: .Cx
        !            36: .Cx \&[
        !            37: .Fl bap
        !            38: .Cx \&\ |\ \&
        !            39: .Fl nbap
        !            40: .Cx \&]
        !            41: .Cx
        !            42: .Cx \&[
        !            43: .Fl bbb
        !            44: .Cx \&\ |\ \&
        !            45: .Fl nbbb
        !            46: .Cx \&]
        !            47: .Cx
        !            48: .Cx \&[
        !            49: .Fl bc
        !            50: .Cx \&\ |\ \&
        !            51: .Fl nbc
        !            52: .Cx \&]
        !            53: .Cx
        !            54: .Op Fl bl
        !            55: .Op Fl br
        !            56: .Oo
        !            57: .Op Fl c Ar n
        !            58: .Op Fl cd Ar n
        !            59: .Oo
        !            60: .Cx \&[
        !            61: .Fl cdb
        !            62: .Cx \&\ |\ \&
        !            63: .Fl ncdb
        !            64: .Cx \&]
        !            65: .Cx
        !            66: .Cx \&[
        !            67: .Fl ce
        !            68: .Cx \&\ |\ \&
        !            69: .Fl nce
        !            70: .Cx \&]
        !            71: .Cx
        !            72: .Oo
        !            73: .Op Fl ci Ar n
        !            74: .Op Fl cli Ar n
        !            75: .Op Fl d Ar n
        !            76: .Op Fl di Ar n
        !            77: .Oo
        !            78: .Cx \&[
        !            79: .Fl fc1
        !            80: .Cx \&\ |\ \&
        !            81: .Fl nfc1
        !            82: .Cx \&]
        !            83: .Cx
        !            84: .Oo
        !            85: .Op Fl i Ar n
        !            86: .Oo
        !            87: .Cx \&[
        !            88: .Fl ip
        !            89: .Cx \&\ |\ \&
        !            90: .Fl nip
        !            91: .Cx \&]
        !            92: .Cx
        !            93: .Oo
        !            94: .Op Fl l Ar n
        !            95: .Op Fl lc Ar n
        !            96: .Oo
        !            97: .Cx \&[
        !            98: .Fl lp
        !            99: .Cx \&\ |\ \&
        !           100: .Fl nlp
        !           101: .Cx \&]
        !           102: .Cx
        !           103: .Op Fl npro
        !           104: .Cx \&[
        !           105: .Fl pcs
        !           106: .Cx \&\ |\ \&
        !           107: .Fl npcs
        !           108: .Cx \&]
        !           109: .Cx
        !           110: .Cx \&[
        !           111: .Fl psl
        !           112: .Cx \&\ |\ \&
        !           113: .Fl npsl
        !           114: .Cx \&]
        !           115: .Cx
        !           116: .Cx \&[
        !           117: .Fl sc
        !           118: .Cx \&\ |\ \&
        !           119: .Fl nsc
        !           120: .Cx \&]
        !           121: .Cx
        !           122: .Cx \&[
        !           123: .Fl sob
        !           124: .Cx \&\ |\ \&
        !           125: .Fl nsob
        !           126: .Cx \&]
        !           127: .Cx
        !           128: .Op Fl st
        !           129: .Op Fl troff
        !           130: .Cx \&[
        !           131: .Fl v
        !           132: .Cx \&\ |\ \&
        !           133: .Fl nv
        !           134: .Cx \&]
        !           135: .Cx
        !           136: .Sh DESCRIPTION
        !           137: .Nm Indent
        !           138: is a
        !           139: .Ar C
        !           140: program formatter.  It reformats the
        !           141: .Ar C
        !           142: program in the
        !           143: .Ar input-file
        !           144: according to the switches.  The switches which can be
        !           145: specified are described below. They may appear before or after the file
        !           146: names.
        !           147: .Pp
        !           148: .Sy NOTE  :
        !           149: If you only specify an
        !           150: .Ar input-file  ,
        !           151: the formatting is
        !           152: done `in-place', that is, the formatted file is written back into
        !           153: .Ar input-file
        !           154: and a backup copy of
        !           155: .Ar input-file
        !           156: is written in the current directory.  If
        !           157: .Ar input-file
        !           158: is named
        !           159: .Sq Pa /blah/blah/file ,
        !           160: the backup file is named
        !           161: .Pa file.BAK .
        !           162: .Pp
        !           163: If
        !           164: .Ar output-file
        !           165: is specified,
        !           166: .Nm indent
        !           167: checks to make sure it is different from
        !           168: .Ar input-file  .
        !           169: .Pp
        !           170: The options listed below control the formatting style imposed by
        !           171: .Nm indent  .
        !           172: .Tw Op
        !           173: .Tp Fl bad , nbad
        !           174: If
        !           175: .Fl bad
        !           176: is specified, a blank line is forced after every block of
        !           177: declarations.  Default:
        !           178: .Fl nbad  .
        !           179: .Tp Fl bap , nbap
        !           180: If
        !           181: .Fl bap
        !           182: is specified, a blank line is forced after every procedure body.  Default:
        !           183: .Fl nbap .
        !           184: .Tp Fl bbb , nbbb
        !           185: If
        !           186: .Fl bbb
        !           187: is specified, a blank line is forced before every block comment.  Default:
        !           188: .Fl nbbb .
        !           189: .Tp Fl bc , nbc
        !           190: If
        !           191: .Fl bc
        !           192: is specified, then a newline is forced after each comma in a declaration.
        !           193: .Fl nbc
        !           194: turns off this option.  The default is
        !           195: .Fl bc  .
        !           196: .Tp Fl br , bl
        !           197: Specifying
        !           198: .Fl bl
        !           199: lines up compound statements like this:
        !           200: .ne 4
        !           201: .Ds I
        !           202: if (...)
        !           203: {
        !           204:   code
        !           205: }
        !           206: .De
        !           207: Specifying
        !           208: .Fl br
        !           209: (the default) makes them look like this:
        !           210: .ne 3
        !           211: .Ds I
        !           212: if (...) {
        !           213:   code
        !           214: }
        !           215: .De
        !           216: .Pp
        !           217: .Tp Fl c n
        !           218: The column in which comments on code start.  The default is 33.
        !           219: .Tp Fl cd n
        !           220: The column in which comments on declarations start.  The default
        !           221: is for these comments to start in the same column as those on code.
        !           222: .Tp Fl cdb , ncdb
        !           223: Enables (disables) the placement of comment delimiters on blank lines.  With
        !           224: this option enabled, comments look like this:
        !           225: .Ds I
        !           226: .ne 3
        !           227:        /*
        !           228:        * this is a comment
        !           229:        */
        !           230: .De
        !           231: Rather than like this:
        !           232: .Ds I
        !           233:        /* this is a comment */
        !           234: .De
        !           235: This only affects block comments, not comments to the right of
        !           236: code.  The default is
        !           237: .Fl cdb  .
        !           238: .Tp Fl ce , nce
        !           239: Enables (disables) forcing `else's to cuddle up to the immediately preceding
        !           240: `}'.  The default is
        !           241: .Fl ce  .
        !           242: .Tp Cx Fl ci
        !           243: .Ar n
        !           244: .Cx
        !           245: Sets the continuation indent to be
        !           246: .Ar n  .
        !           247: Continuation
        !           248: lines will be indented that far from the beginning of the first line of the
        !           249: statement.  Parenthesized expressions have extra indentation added to
        !           250: indicate the nesting, unless
        !           251: .Fl lp
        !           252: is in effect.
        !           253: .Fl ci
        !           254: defaults to the same value as
        !           255: .Fl i  .
        !           256: .Tp Cx Fl cli
        !           257: .Ar n
        !           258: .Cx
        !           259: Causes case labels to be indented
        !           260: .Ar n
        !           261: tab stops to the right of the containing
        !           262: .Ic switch
        !           263: statement.
        !           264: .Fl cli0 .5
        !           265: causes case labels to be indented half a tab stop.  The
        !           266: default is
        !           267: .Fl cli0  .
        !           268: .Tp Cx Fl d
        !           269: .Ar n
        !           270: .Cx
        !           271: Controls the placement of comments which are not to the
        !           272: right of code.  The default
        !           273: .Fl d1
        !           274: means that such comments are placed one indentation level to the
        !           275: left of code.  Specifying
        !           276: .Fl d0
        !           277: lines up these comments with the code.  See the section on comment
        !           278: indentation below.
        !           279: .Tp Cx Fl di
        !           280: .Ar n
        !           281: .Cx
        !           282: Specifies the indentation, in character positions, from a declaration keyword
        !           283: to the following identifier.  The default is
        !           284: .Fl di16  .
        !           285: .Tp Fl dj , ndj
        !           286: .Fl dj
        !           287: left justifies declarations.
        !           288: .Fl ndj
        !           289: indents declarations the same as code.  The default is
        !           290: .Fl ndj  .
        !           291: .Tp Fl ei , nei
        !           292: Enables (disables) special
        !           293: .Ic else-if
        !           294: processing.  If it's enabled, an
        !           295: .Ic if
        !           296: following an
        !           297: .Ic else
        !           298: will have the same indentation as the preceding
        !           299: .Ic if
        !           300: statement.
        !           301: .Tp Fl fc1 , nfc1
        !           302: Enables (disables) the formatting of comments that start in column 1.
        !           303: Often, comments whose leading `/' is in column 1 have been carefully
        !           304: hand formatted by the programmer.  In such cases,
        !           305: .Fl nfc1
        !           306: should be
        !           307: used.  The default is
        !           308: .Fl fc1  .
        !           309: .Tp Cx Fl i
        !           310: .Ar n
        !           311: .Cx
        !           312: The number of spaces for one indentation level.  The default is 4.
        !           313: .Tp Fl ip , nip
        !           314: Enables (disables) the indentation of parameter declarations from the left
        !           315: margin.  The default is
        !           316: .Fl ip  .
        !           317: .Tp Cx Fl l
        !           318: .Ar n
        !           319: .Cx
        !           320: Maximum length of an output line.  The default is 75.
        !           321: .Tp Fl lp , nlp
        !           322: Lines up code surrounded by parenthesis in continuation lines.  If a line
        !           323: has a left paren which is not closed on that line, then continuation lines
        !           324: will be lined up to start at the character position just after the left
        !           325: paren.  For example, here is how a piece of continued code looks with
        !           326: .Fl nlp
        !           327: in effect:
        !           328: .ne 2
        !           329: .Ds I
        !           330: .Li p1 = first_procedure(second_procedure(p2, p3),
        !           331: .Li \ \ third_procedure(p4,p5));
        !           332: .De
        !           333: .ne 5
        !           334: With
        !           335: .Fl lp
        !           336: in effect (the default) the code looks somewhat clearer:
        !           337: .Ds I
        !           338: .Li p1\ =\ first_procedure(second_procedure(p2,\ p3),
        !           339: .Li \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,p5));
        !           340: .De
        !           341: .ne 5
        !           342: Inserting two more newlines we get:
        !           343: .Ds I
        !           344: .Li p1\ =\ first_procedure(second_procedure(p2,
        !           345: .Li \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p3),
        !           346: .Li \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4
        !           347: .Li \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p5));
        !           348: .De
        !           349: .Pp
        !           350: .Tp Fl npro
        !           351: Causes the profile files,
        !           352: .Sq Pa ./.indent.pro
        !           353: and
        !           354: .Sq Pa ~/.indent.pro ,
        !           355: to be ignored.
        !           356: .Tp Fl pcs , npcs
        !           357: If true
        !           358: .Pq Fl pcs
        !           359: all procedure calls will have a space inserted between
        !           360: the name and the `('.  The default is
        !           361: .Fl npcs  .
        !           362: .Tp Fl psl , npsl
        !           363: If true
        !           364: .Pq Fl psl
        !           365: the names of procedures being defined are placed in
        !           366: column 1 \- their types, if any, will be left on the previous lines.  The
        !           367: default is
        !           368: .Fl psl  .
        !           369: .Tp Fl sc , nsc
        !           370: Enables (disables) the placement of asterisks (`*'s) at the left edge of all
        !           371: comments.
        !           372: .Tp Fl sob , nsob
        !           373: If
        !           374: .Fl sob
        !           375: is specified, indent will swallow optional blank lines.  You can use this to
        !           376: get rid of blank lines after declarations.  Default:
        !           377: .Fl nsob  .
        !           378: .Tp Fl st
        !           379: Causes
        !           380: .Nm indent
        !           381: to take its input from stdin, and put its output to stdout.
        !           382: .Tp Cx Fl T
        !           383: .Ar typename
        !           384: .Cx
        !           385: Adds
        !           386: .Ar typename
        !           387: to the list of type keywords.  Names accumulate:
        !           388: .Fl T
        !           389: can be specified more than once.  You need to specify all the typenames that
        !           390: appear in your program that are defined by
        !           391: .Ic typedef
        !           392: \- nothing will be
        !           393: harmed if you miss a few, but the program won't be formatted as nicely as
        !           394: it should.  This sounds like a painful thing to have to do, but it's really
        !           395: a symptom of a problem in C:
        !           396: .Ic typedef
        !           397: causes a syntactic change in the
        !           398: language and
        !           399: .Nm indent
        !           400: can't find all
        !           401: instances of
        !           402: .Ic typedef .
        !           403: .Tp Fl troff
        !           404: Causes
        !           405: .Nm indent
        !           406: to format the program for processing by troff.  It will produce a fancy
        !           407: listing in much the same spirit as
        !           408: .Xr vgrind 1 .
        !           409: If the output file is not specified, the default is standard output,
        !           410: rather than formatting in place.
        !           411: .Tp Fl v , nv
        !           412: .Fl v
        !           413: turns on `verbose' mode;
        !           414: .Fl nv
        !           415: turns it off.  When in verbose mode,
        !           416: .Nm indent
        !           417: reports when it splits one line of input into two or more lines of output,
        !           418: and gives some size statistics at completion. The default is
        !           419: .Fl nv  .
        !           420: .Tp
        !           421: .Pp
        !           422: You may set up your own `profile' of defaults to
        !           423: .Nm indent
        !           424: by creating a file called
        !           425: .Pa .indent.pro
        !           426: in your login directory and/or the current directory and including
        !           427: whatever switches you like.  A `.indent.pro' in the current directory takes
        !           428: precedence over the one in your login directory.  If
        !           429: .Nm indent
        !           430: is run and a profile file exists, then it is read to set up the program's
        !           431: defaults.  Switches on the command line, though, always override profile
        !           432: switches.  The switches should be separated by spaces, tabs or newlines.
        !           433: .Pp
        !           434: .Ss Comments
        !           435: .Sq Em Box
        !           436: .Em comments .
        !           437: .Nm Indent
        !           438: assumes that any comment with a dash or star immediately after the start of
        !           439: comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars.
        !           440: Each line of such a comment is left unchanged, except that its indentation
        !           441: may be adjusted to account for the change in indentation of the first line
        !           442: of the comment.
        !           443: .Pp
        !           444: .Em Straight text .
        !           445: All other comments are treated as straight text.
        !           446: .Nm Indent
        !           447: fits as many words (separated by blanks, tabs, or newlines) on a
        !           448: line as possible.  Blank lines break paragraphs.
        !           449: .Pp
        !           450: .Ss Comment indentation
        !           451: If a comment is on a line with code it is started in the `comment column',
        !           452: which is set by the
        !           453: .Cx Fl c
        !           454: .Ar n
        !           455: .Cx
        !           456: command line parameter.  Otherwise, the comment is started at
        !           457: .Ar n
        !           458: indentation levels less than where code is currently being placed, where
        !           459: .Ar n
        !           460: is specified by the
        !           461: .Cx Fl d
        !           462: .Ar n
        !           463: .Cx
        !           464: command line parameter.  If the code on a line extends past the comment
        !           465: column, the comment starts further to the right, and the right margin may be
        !           466: automatically extended in extreme cases.
        !           467: .Pp
        !           468: .Ss Preprocessor lines
        !           469: In general,
        !           470: .Nm indent
        !           471: leaves preprocessor lines alone.  The only
        !           472: reformatting that it will do is to straighten up trailing comments.  It
        !           473: leaves embedded comments alone.  Conditional compilation
        !           474: .Pq Ic #ifdef...#endif
        !           475: is recognized and
        !           476: .Nm indent
        !           477: attempts to correctly
        !           478: compensate for the syntactic peculiarities introduced.
        !           479: .Pp
        !           480: .Ss C syntax
        !           481: .Nm Indent
        !           482: understands a substantial amount about the syntax of C, but it
        !           483: has a `forgiving' parser.  It attempts to cope with the usual sorts of
        !           484: incomplete and misformed syntax.  In particular, the use of macros like:
        !           485: .Dl #define forever for(;;)
        !           486: is handled properly.
        !           487: .Sh ENVIRONMENT
        !           488: .Nm Indent
        !           489: uses the
        !           490: .Ev HOME
        !           491: environment variable.
        !           492: .Sh FILES
        !           493: .Dw \&./.indent.pro
        !           494: .Di L
        !           495: .Dp Pa \&./.indent.pro
        !           496: profile file
        !           497: .Dp Pa ~/.indent.pro
        !           498: profile file
        !           499: .Dp
        !           500: .Sh HISTORY
        !           501: .Nm Indent
        !           502: appeared in 4.2 BSD.
        !           503: .Sh BUGS
        !           504: .Nm Indent
        !           505: has even more switches than
        !           506: .Xr ls 1 .
        !           507: .Pp
        !           508: .ne 5
        !           509: A common mistake that often causes grief is typing:
        !           510: .Dl indent *.c
        !           511: to the shell in an attempt to indent all the
        !           512: .Nm C
        !           513: programs in a directory.
        !           514: This is probably a bug, not a feature.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.