diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/indent.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/indent.1 | 2185 |
1 files changed, 2185 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/indent.1 b/upstream/mageia-cauldron/man1/indent.1 new file mode 100644 index 00000000..c5307b67 --- /dev/null +++ b/upstream/mageia-cauldron/man1/indent.1 @@ -0,0 +1,2185 @@ +.TH INDENT 1 +.SH "NAME" +indent \- changes the appearance of a C program by inserting or deleting whitespace. +.SH "SYNOPSIS" +.B "indent " +[options] [input\-files] +.sp +.B "indent " +[options] [single\-input\-file] [\-o output\-file] +.sp +.B "indent " +\-\-version +.SH "DESCRIPTION" +This man page is generated from the file \fIindent.texinfo\fR. +This is Edition of "The \fBindent\fR Manual", +for Indent Version , last updated . + +The \fBindent\fR program +can be used to make code easier to read. It can also convert from one +style of writing C to another. + +.B indent\fR understands a substantial amount about the syntax of C, +but it also attempts to cope with incomplete and misformed syntax. + +In version 1.2 and more recent versions, the GNU style of indenting is +the default. +.SH "OPTIONS" + +.TP 4 +.B -as\fR, \fB--align-with-spaces\fR +If using tabs for indentation, use spaces for alignment. +.br +See \fB\ INDENTATION\fR. +.TP +.B -bad\fR, \fB--blank-lines-after-declarations\fR +Force blank lines after the declarations. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -bap\fR, \fB--blank-lines-after-procedures\fR +Force blank lines after procedure bodies. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -bbb\fR, \fB--blank-lines-before-block-comments\fR +Force blank lines before block comments. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -bbo\fR, \fB--break-before-boolean-operator\fR +Prefer to break long lines before boolean operators. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -bc\fR, \fB--blank-lines-after-commas\fR +Force newline after comma in declaration. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -bl\fR, \fB--braces-after-if-line\fR +Put braces on line after \fBif\fR, etc. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -blf\fR, \fB--braces-after-func-def-line\fR +Put braces on line following function definition line. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -bli\fIn\fB\fR, \fB--brace-indent\fIn\fB\fR +Indent braces \fIn\fR spaces. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -bls\fR, \fB--braces-after-struct-decl-line\fR +Put braces on the line after \fBstruct\fR declaration lines. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -br\fR, \fB--braces-on-if-line\fR +Put braces on line with \fBif\fR, etc. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -brf\fR, \fB--braces-on-func-def-line\fR +Put braces on function definition line. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -brs\fR, \fB--braces-on-struct-decl-line\fR +Put braces on \fBstruct\fR declaration line. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -bs\fR, \fB--Bill-Shannon\fR, \fB--blank-before-sizeof\fR +Put a space between \fBsizeof\fR and its argument. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -c\fIn\fB\fR, \fB--comment-indentation\fIn\fB\fR +Put comments to the right of code in column \fIn\fR. +.br +See \fB\ COMMENTS\fR. +.TP +.B -cbi\fIn\fB\fR, \fB--case-brace-indentation\fIn\fB\fR +Indent braces after a case label N spaces. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -cd\fIn\fB\fR, \fB--declaration-comment-column\fIn\fB\fR +Put comments to the right of the declarations in column \fIn\fR. +.br +See \fB\ COMMENTS\fR. +.TP +.B -cdb\fR, \fB--comment-delimiters-on-blank-lines\fR +Put comment delimiters on blank lines. +.br +See \fB\ COMMENTS\fR. +.TP +.B -cdw\fR, \fB--cuddle-do-while\fR +Cuddle while of \fBdo {} while;\fR and preceding \(oq}\(cq. +.br +See \fB\ COMMENTS\fR. +.TP +.B -ce\fR, \fB--cuddle-else\fR +Cuddle else and preceding \(oq}\(cq. +.br +See \fB\ COMMENTS\fR. +.TP +.B -ci\fIn\fB\fR, \fB--continuation-indentation\fIn\fB\fR +Continuation indent of \fIn\fR spaces. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -cli\fIn\fB\fR, \fB--case-indentation\fIn\fB\fR +Case label indent of \fIn\fR spaces. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -cp\fIn\fB\fR, \fB--else-endif-column\fIn\fB\fR +Put comments to the right of \fB#else\fR and \fB +#endif\fR statements in column \fIn\fR. +.br +See \fB\ COMMENTS\fR. +.TP +.B -cs\fR, \fB--space-after-cast\fR +Put a space after a cast operator. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -d\fIn\fB\fR, \fB--line-comments-indentation\fIn\fB\fR +Set indentation of comments not to the right +of code to \fIn\fR spaces. +.br +See \fB\ COMMENTS\fR. +.TP +.B -bfda\fR, \fB--break-function-decl-args\fR +Break the line before all arguments in a declaration. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -bfde\fR, \fB--break-function-decl-args-end\fR +Break the line after the last argument in a declaration. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -dj\fR, \fB--left-justify-declarations\fR +If -cd 0 is used then comments after declarations are left justified +behind the declaration. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -di\fIn\fB\fR, \fB--declaration-indentation\fIn\fB\fR +Put variables in column \fIn\fR. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -fc1\fR, \fB--format-first-column-comments\fR +Format comments in the first column. +.br +See \fB\ COMMENTS\fR. +.TP +.B -fca\fR, \fB--format-all-comments\fR +Do not disable all formatting of comments. +.br +See \fB\ COMMENTS\fR. +.TP +.B -fnc\fR, \fB--fix-nested-comments\fR +Fix nested comments. +.br +See \fB\ COMMENTS\fR. +.TP +.B -gnu\fR, \fB--gnu-style\fR +Use GNU coding style. This is the default. +.br +See \fB\ COMMON\ STYLES\fR. +.TP +.B -gts\fR, \fB--gettext-strings\fR +Treat gettext \fB_("...")\fR and \fBN_("...")\fR as strings rather than as functions. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -hnl\fR, \fB--honour-newlines\fR +Prefer to break long lines at the position of newlines in the input. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -i\fIn\fB\fR, \fB--indent-level\fIn\fB\fR +Set indentation level to \fIn\fR spaces. +.br +See \fB\ INDENTATION\fR. +.TP +.B -il\fIn\fB\fR, \fB--indent-label\fIn\fB\fR +Set offset for labels to column \fIn\fR. +.br +See \fB\ INDENTATION\fR. +.TP +.B -ip\fIn\fB\fR, \fB--parameter-indentation\fIn\fB\fR +Indent parameter types in old-style function +definitions by \fIn\fR spaces. +.br +See \fB\ INDENTATION\fR. +.TP +.B -kr\fR, \fB--k-and-r-style\fR +Use Kernighan & Ritchie coding style. +.br +See \fB\ COMMON\ STYLES\fR. +.TP +.B -l\fIn\fB\fR, \fB--line-length\fIn\fB\fR +Set maximum line length for non-comment lines to \fIn\fR. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -lc\fIn\fB\fR, \fB--comment-line-length\fIn\fB\fR +Set maximum line length for comment formatting to \fIn\fR. +.br +See \fB\ COMMENTS\fR. +.TP +.B -linux\fR, \fB--linux-style\fR +Use Linux coding style. +.br +See \fB\ COMMON\ STYLES\fR. +.TP +.B -lp\fR, \fB--continue-at-parentheses\fR +Line up continued lines at parentheses. +.br +See \fB\ INDENTATION\fR. +.TP +.B -lps\fR, \fB--leave-preprocessor-space\fR +Leave space between \(oq#\(cq and preprocessor directive. +.br +See \fB\ INDENTATION\fR. +.TP +.B -nlps\fR, \fB--remove-preprocessor-space\fR +Remove space between \(oq#\(cq and preprocessor directive. +.br +See \fB\ INDENTATION\fR. +.TP +.B -nbad\fR, \fB--no-blank-lines-after-declarations\fR +Do not force blank lines after declarations. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -nbap\fR, \fB--no-blank-lines-after-procedures\fR +Do not force blank lines after procedure bodies. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -nbbo\fR, \fB--break-after-boolean-operator\fR +Do not prefer to break long lines before boolean operators. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -nbc\fR, \fB--no-blank-lines-after-commas\fR +Do not force newlines after commas in declarations. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -nbfda\fR, \fB--dont-break-function-decl-args\fR +Don\(cqt put each argument in a function declaration on a separate line. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -ncdb\fR, \fB--no-comment-delimiters-on-blank-lines\fR +Do not put comment delimiters on blank lines. +.br +See \fB\ COMMENTS\fR. +.TP +.B -ncdw\fR, \fB--dont-cuddle-do-while\fR +Do not cuddle \fB}\fR and the \fBwhile\fR of a \fBdo {} while;\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -nce\fR, \fB--dont-cuddle-else\fR +Do not cuddle \fB}\fR and \fBelse\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -ncs\fR, \fB--no-space-after-casts\fR +Do not put a space after cast operators. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -ndj\fIn\fB\fR, \fB--dont-left-justify-declarations\fR +Comments after declarations are treated the same as +comments after other statements. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -nfc1\fR, \fB--dont-format-first-column-comments\fR +Do not format comments in the first column as normal. +.br +See \fB\ COMMENTS\fR. +.TP +.B -nfca\fR, \fB--dont-format-comments\fR +Do not format any comments. +.br +See \fB\ COMMENTS\fR. +.TP +.B -ngts\fR, \fB--no-gettext-strings\fR +Treat gettext \fB_("...")\fR and \fBN_("...")\fR as normal functions. This is the default. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -nhnl\fR, \fB--ignore-newlines\fR +Do not prefer to break long lines at the position of newlines in the input. +.br +See \fB\ BREAKING\ LONG\ LINES\fR. +.TP +.B -nip\fR, \fB--no-parameter-indentation\fR +Zero width indentation for parameters. +.br +See \fB\ INDENTATION\fR. +.TP +.B -nlp\fR, \fB--dont-line-up-parentheses\fR +Do not line up parentheses. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -npcs\fR, \fB--no-space-after-function-call-names\fR +Do not put space after the function in function calls. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -nprs\fR, \fB--no-space-after-parentheses\fR +Do not put a space after every \(cq(\(cq and before every \(cq)\(cq. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -npsl\fR, \fB--dont-break-procedure-type\fR +Put the type of a procedure on the same line as its name. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -nsaf\fR, \fB--no-space-after-for\fR +Do not put a space after every \fBfor\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -nsai\fR, \fB--no-space-after-if\fR +Do not put a space after every \fBif\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -nsaw\fR, \fB--no-space-after-while\fR +Do not put a space after every \fBwhile\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -nsc\fR, \fB--dont-star-comments\fR +Do not put the \(oq*\(cq character at the left of comments. +.br +See \fB\ COMMENTS\fR. +.TP +.B -nsob\fR, \fB--leave-optional-blank-lines\fR +Do not swallow optional blank lines. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -nss\fR, \fB--dont-space-special-semicolon\fR +Do not force a space before the semicolon after certain statements. +Disables \(oq-ss\(cq. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -ntac\fR, \fB--dont-tab-align-comments\fR +Do not pad comments out to the nearest tabstop. +.br +See \fB\ COMMENTS\fR. +.TP +.B -nut\fR, \fB--no-tabs\fR +Use spaces instead of tabs. +.br +See \fB\ INDENTATION\fR. +.TP +.B -nv\fR, \fB--no-verbosity\fR +Disable verbose mode. +.br +See \fB\ MISCELLANEOUS\ OPTIONS\fR. +.TP +.B -orig\fR, \fB--original\fR +Use the original Berkeley coding style. +.br +See \fB\ COMMON\ STYLES\fR. +.TP +.B -npro\fR, \fB--ignore-profile\fR +Do not read \(oq.indent.pro\(cq files. +.br +See \fB\ INVOKING\ INDENT\fR. +.TP +.B -pal\fR, \fB--pointer-align-left\fR +Put asterisks in pointer declarations on the left of spaces, next to +types: \(oq\(oqchar* p\(cq\(cq. +.TP +.B -par\fR, \fB--pointer-align-right\fR +Put asterisks in pointer declarations on the right of spaces, next to +variable names: \(oq\(oqchar *p\(cq\(cq. This is the default behavior. +.TP +.B -pcs\fR, \fB--space-after-procedure-calls\fR +Insert a space between the name of the +procedure being called and the \(oq(\(cq. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -pi\fIn\fB\fR, \fB--paren-indentation\fIn\fB\fR +Specify the extra indentation per open parentheses \(cq(\(cq when a +statement is broken.See \fB\ STATEMENTS\fR. +.TP +.B -pmt\fR, \fB--preserve-mtime\fR +Preserve access and modification times on output files.See \fB\ MISCELLANEOUS\ OPTIONS\fR. +.TP +.B -ppi\fIn\fB\fR, \fB--preprocessor-indentation\fIn\fB\fR +Specify the indentation for preprocessor conditional statements.See \fB\ INDENTATION\fR. +.TP +.B -prs\fR, \fB--space-after-parentheses\fR +Put a space after every \(cq(\(cq and before every \(cq)\(cq. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -psl\fR, \fB--procnames-start-lines\fR +Put the type of a procedure on the line before its name. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -saf\fR, \fB--space-after-for\fR +Put a space after each \fBfor\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -sai\fR, \fB--space-after-if\fR +Put a space after each \fBif\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -sar\fR, \fB--spaces-around-initializers\fR +Put a space after the \(oq{\(cq and before the \(oq}\(cq in initializers. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -saw\fR, \fB--space-after-while\fR +Put a space after each \fBwhile\fR. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -sbi\fIn\fB\fR, \fB--struct-brace-indentation\fIn\fB\fR +Indent braces of a struct, union or enum N spaces. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -sc\fR, \fB--start-left-side-of-comments\fR +Put the \(oq*\(cq character at the left of comments. +.br +See \fB\ COMMENTS\fR. +.TP +.B -slc\fR, \fB--single-line-conditionals\fR +Allow for unbraced conditionals (\fBif\fR, \fBelse\fR, etc.) to have +their inner statement on the same line. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -sob\fR, \fB--swallow-optional-blank-lines\fR +Swallow optional blank lines. +.br +See \fB\ BLANK\ LINES\fR. +.TP +.B -ss\fR, \fB--space-special-semicolon\fR +On one-line \fBfor\fR and \fBwhile\fR statements, +force a blank before the semicolon. +.br +See \fB\ STATEMENTS\fR. +.TP +.B -st\fR, \fB--standard-output\fR +Write to standard output. +.br +See \fB\ INVOKING\ INDENT\fR. +.TP +.B -T\fR +Tell \fBindent\fR the name of typenames. +.br +See \fB\ DECLARATIONS\fR. +.TP +.B -ts\fIn\fB\fR, \fB--tab-size\fIn\fB\fR +Set tab size to \fIn\fR spaces. +.br +See \fB\ INDENTATION\fR. +.TP +.B -ut\fR, \fB--use-tabs\fR +Use tabs. This is the default. +.br +See \fB\ INDENTATION\fR. +.TP +.B -v\fR, \fB--verbose\fR +Enable verbose mode. +.br +See \fB\ MISCELLANEOUS\ OPTIONS\fR. +.TP +.B -version\fR +Output the version number of \fBindent\fR. +.br +See \fB\ MISCELLANEOUS\ OPTIONS\fR. + +.SH "INVOKING INDENT" + +As of version 1.3, the format of the \fBindent\fR command is: + +.in +5 +.nf +.na + +indent [\fIoptions\fR] [\fIinput-files\fR] + +indent [\fIoptions\fR] [\fIsingle-input-file\fR] [-o \fIoutput-file\fR] + +.in -5 +.ad +.fi + +This format is different from earlier versions and other versions of +.B indent\fR. + +In the first form, one or more input files are specified. \fBindent\fR +makes a backup copy of each file, and the original file is replaced with +its indented version. See \fBBACKUP\ FILES\fR, for an explanation of how +backups are made. + +In the second form, only one input file is specified. In this case, or +when the standard input is used, you may specify an output file after +the \(oq-o\(cq option. + +To cause \fBindent\fR to write to standard output, use the \(oq-st\(cq +option. This is only allowed when there is only one input file, or when +the standard input is used. + +If no input files are named, the standard input is read for input. +Also, if a filename named \(oq-\(cq is specified, then the standard input +is read. + +As an example, each of the following commands will input the program +\(oqslithy_toves.c\(cq and write its indented text to +\(oqslithy_toves.out\(cq: + +.in +5 +.nf +.na + +indent slithy_toves.c -o slithy_toves.out + +indent -st slithy_toves.c > slithy_toves.out + +cat slithy_toves.c | indent -o slithy_toves.out + +.in -5 +.ad +.fi + +Most other options to \fBindent\fR control how programs are formatted. +As of version 1.2, \fBindent\fR also recognizes a long name for each +option name. Long options are prefixed by either \(oq--\(cq or +\(oq+\(cq. +[ \(oq+\(cq is being superseded by \(oq--\(cq to +maintain consistency with the POSIX standard.] + In most of this document, +the traditional, short names are used for the sake of brevity. +See \fBOPTION\ SUMMARY\fR, for a list of options, including both long and +short names. + +Here is another example: + +.in +5 +.nf +.na +indent -br test/metabolism.c -l85 +.in -5 +.ad +.fi + +This will indent the program \(oqtest/metabolism.c\(cq using the +\(oq-br\(cq and \(oq-l85\(cq options, write the output back to +\(oqtest/metabolism.c\(cq, and write the original contents of +\(oqtest/metabolism.c\(cq to a backup file in the directory \(oqtest\(cq. + +Equivalent invocations using long option names for this example would +be: + +.in +5 +.nf +.na + +indent --braces-on-if-line --line-length185 test/metabolism.c + +indent +braces-on-if-line +line-length185 test/metabolism.c + +.in -5 +.ad +.fi + +If you find that you often use \fBindent\fR with the same options, you +may put those options into a file named \(oq.indent.pro\(cq. +.B indent\fR will look for a profile file in three places. First it will check +the environment variable \fBINDENT_PROFILE\fR. If that exists its value +is expected to name the file that is to be used. If the environment variable does +not exist, indent looks for \(oq.indent.pro\(cq in the current directory + and use that if found. Finally \fBindent\fR will search +your home directory for \(oq.indent.pro\(cq and use that file if it is +found. This behaviour is different from that of other versions of +.B indent\fR, which load both files if they both exist. + +The format of \(oq.indent.pro\(cq is simply a list of options, just as +they would appear on the command line, separated by white space (tabs, +spaces, and newlines). Options in \(oq.indent.pro\(cq may be surrounded by C +or C++ comments, in which case they are ignored. + +Command line switches are handled \fIafter\fR processing +\(oq .indent.pro\(cq. Options specified later override arguments +specified earlier, with one exception: Explicitly specified options +always override background options (See \fBCOMMON\ STYLES\fR). You can +prevent \fBindent\fR from reading an \(oq.indent.pro\(cq file by +specifying the \(oq-npro\(cq option. + +.SH "BACKUP FILES" + +As of version 1.3, GNU \fBindent\fR makes GNU-style backup files, the +same way GNU Emacs does. This means that either \fIsimple\fR or +.I numbered\fR backup filenames may be made. + +Simple backup file names are generated by appending a suffix to the +original file name. The default for this suffix is the +one-character string \(oq~\(cq (tilde). Thus, the backup file for +\(oqpython.c\(cq would be \(oqpython.c~\(cq. + +Instead of the default, you may specify any string as a suffix by +setting the environment variable \fBSIMPLE_BACKUP_SUFFIX\fR to +your preferred suffix. + +Numbered backup versions of a file \(oqmomeraths.c\(cq look like +\(oqmomeraths.c.~23~\(cq, where 23 is the version of this particular +backup. When making a numbered backup of the file \(oqsrc/momeraths.c\(cq, +the backup file will be named \(oqsrc/momeraths.c.~\fIV\fR~\(cq, where +.I V\fR is one greater than the highest version currently existing in +the directory \(oqsrc\(cq. The environment variable \fBVERSION_WIDTH\fR +controls the number of digits, using left zero padding when necessary. +For instance, setting this variable to "2" will lead to the backup +file being named \(oqmomeraths.c.~04~\(cq. + +The type of backup file made is controlled by the value of the +environment variable \fBVERSION_CONTROL\fR. If it is the string +\(oqsimple\(cq, then only simple backups will be made. If its value is +the string \(oqnumbered\(cq, then numbered backups will be made. If its +value is \(oqnumbered-existing\(cq, then numbered backups will be made if +there \fIalready exist\fR numbered backups for the file being indented; +otherwise, a simple backup is made. If \fBVERSION_CONTROL\fR is not +set, then \fBindent\fR assumes the behaviour of +\(oqnumbered-existing\(cq. + +Other versions of \fBindent\fR use the suffix \(oq.BAK\(cq in naming +backup files. This behaviour can be emulated by setting +.B SIMPLE_BACKUP_SUFFIX\fR to \(oq.BAK\(cq. + +Note also that other versions of \fBindent\fR make backups in the +current directory, rather than in the directory of the source file as +GNU \fBindent\fR now does. + +.SH "COMMON STYLES" + +There are several common styles of C code, including the GNU style, the +Kernighan & Ritchie style, and the original Berkeley style. A style may +be selected with a single \fIbackground\fR option, which specifies a set +of values for all other options. However, explicitly specified options +always override options implied by a background option. + +As of version 1.2, the default style of GNU \fBindent\fR is the GNU +style. Thus, it is no longer necessary to specify the option +\(oq-gnu\(cq to obtain this format, although doing so will not cause an +error. Option settings which correspond to the GNU style are: + +.in +5 +.nf +.na +-nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2 +-ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -nprs -psl -saf -sai +-saw -nsc -nsob +.in -5 +.ad +.fi + +The GNU coding style is that preferred by the GNU project. It is the +style that the GNU Emacs C mode encourages and which is used in the C +portions of GNU Emacs. (People interested in writing programs for +Project GNU should get a copy of "The GNU Coding Standards", which +also covers semantic and portability issues such as memory usage, the +size of integers, etc.) + +The Kernighan & Ritchie style is used throughout their well-known book +"The C Programming Language". It is enabled with the \(oq-kr\(cq +option. The Kernighan & Ritchie style corresponds to the following set +of options: + +.in +5 +.nf +.na +-nbad -bap -bbo -nbc -br -brs -c33 -cd33 -ncdb -ce -ci4 -cli0 +-cp33 -cs -d0 -di1 -nfc1 -nfca -hnl -i4 -ip0 -l75 -lp -npcs +-nprs -npsl -saf -sai -saw -nsc -nsob -nss -par +.in -5 +.ad +.fi + +Kernighan & Ritchie style does not put comments to the right of code in +the same column at all times (nor does it use only one space to the +right of the code), so for this style \fBindent\fR has arbitrarily +chosen column 33. + +The style of the original Berkeley \fBindent\fR may be obtained by +specifying \(oq-orig\(cq (or by specifying \(oq--original\(cq, using the +long option name). This style is equivalent to the following settings: + +.in +5 +.nf +.na +-nbad -nbap -bbo -bc -br -brs -c33 -cd33 -cdb -ce -ci4 -cli0 +-cp33 -di16 -fc1 -fca -hnl -i4 -ip4 -l75 -lp -npcs -nprs -psl +-saf -sai -saw -sc -nsob -nss -ts8 +.in -5 +.ad +.fi + +The Linux style is used in the linux kernel code and drivers. Code +generally has to follow the Linux coding style to be accepted. +This style is equivalent to the following settings: + +.in +5 +.nf +.na +-nbad -bap -nbc -bbo -hnl -br -brs -c33 -cd33 -ncdb -ce -ci4 +-cli0 -d0 -di1 -nfc1 -i8 -ip0 -l80 -lp -npcs -nprs -npsl -sai +-saf -saw -ncs -nsc -sob -nfca -cp33 -ss -ts8 -il1 +.in -5 +.ad +.fi + +.SH "BLANK LINES" + +Various programming styles use blank lines in different places. +.B indent\fR has a number of options to insert or delete blank lines in +specific places. + +The \(oq-bad\(cq option causes \fBindent\fR to force a blank line after +every block of declarations. The \(oq-nbad\(cq option causes +.B indent\fR not to force such blank lines. + +The \(oq-bap\(cq option forces a blank line after every procedure body. +The \(oq-nbap\(cq option forces no such blank line. + +The \(oq-bbb\(cq option forces a blank line before every boxed comment +(See \fBCOMMENTS\fR.) +The \(oq-nbbb\(cq option does not force such blank lines. + +The \(oq-sob\(cq option causes \fBindent\fR to swallow optional blank +lines (that is, any optional blank lines present in the input will be +removed from the output). If the \(oq-nsob\(cq is specified, any blank +lines present in the input file will be copied to the output file. + + +.SH "--blank-lines-after-declarations" + +The \(oq-bad\(cq option forces a blank line after every block of +declarations. The \(oq-nbad\(cq option does not add any such blank +lines. + +For example, given the input +.in +5 +.nf +.na +char *foo; +char *bar; +/* This separates blocks of declarations. */ +int baz; +.in -5 +.ad +.fi + +.B indent -bad\fR produces + +.in +5 +.nf +.na +char *foo; +char *bar; + +/* This separates blocks of declarations. */ +int baz; +.in -5 +.ad +.fi + +and \fBindent -nbad\fR produces + +.in +5 +.nf +.na +char *foo; +char *bar; +/* This separates blocks of declarations. */ +int baz; +.in -5 +.ad +.fi + +.SH "--blank-lines-after-procedures" + +The \(oq-bap\(cq option forces a blank line after every procedure body. + +For example, given the input + +.in +5 +.nf +.na +int +foo () +{ + puts("Hi"); +} +/* The procedure bar is even less interesting. */ +char * +bar () +{ + puts("Hello"); +} +.in -5 +.ad +.fi + +.B indent -bap\fR produces + +.in +5 +.nf +.na +int +foo () +{ + puts ("Hi"); +} + +/* The procedure bar is even less interesting. */ +char * +bar () +{ + puts ("Hello"); +} +.in -5 +.ad +.fi + +and \fBindent -nbap\fR produces + +.in +5 +.nf +.na +int +foo () +{ + puts ("Hi"); +} +/* The procedure bar is even less interesting. */ +char * +bar () +{ + puts ("Hello"); +} +.in -5 +.ad +.fi + +No blank line will be added after the procedure \fBfoo\fR. + +.SH "COMMENTS" + +.B indent\fR formats both C and C++ comments. C comments are begun with +\(oq/*\(cq, terminated with \(oq*/\(cq and may contain newline characters. +C++ comments begin with the delimiter \(oq//\(cq and end at the newline. + +.B indent\fR handles comments differently depending upon their context. +.B indent\fR attempts to distinguish between comments which follow +statements, comments which follow declarations, comments following +preprocessor directives, and comments which are not preceded by code of +any sort, i.e., they begin the text of the line (although not +necessarily in column 1). + +.B indent\fR further distinguishes between comments found outside of +procedures and aggregates, and those found within them. In particular, +comments beginning a line found within a procedure will be indented to +the column at which code is currently indented. The exception to this +is a comment beginning in the leftmost column; such a comment is output +at that column. + +.B indent\fR attempts to leave \fIboxed comments\fR unmodified. The +general idea of such a comment is that it is enclosed in a rectangle or +\(oq\(oqbox\(cq\(cq of stars or dashes to visually set it apart. More precisely, +boxed comments are defined as those in which the initial \(oq/*\(cq is +followed immediately by the character \(oq*\(cq, \(oq=\(cq, \(oq_\(cq, or +\(oq-\(cq, or those in which the beginning comment delimiter (\(oq/*\(cq) +is on a line by itself, and the following line begins with a \(oq*\(cq in +the same column as the star of the opening delimiter. + +Examples of boxed comments are: + +.in +5 +.nf +.na +/********************** + * Comment in a box!! * + **********************/ + + /* + * A different kind of scent, + * for a different kind of comment. + */ +.in -5 +.ad +.fi + +.B indent\fR attempts to leave boxed comments exactly as they are found +in the source file. Thus the indentation of the comment is unchanged, +and its length is not checked in any way. The only alteration made is +that an embedded tab character may be converted into the appropriate +number of spaces. + +If the \(oq-bbb\(cq option is specified, all such boxed comments will be +preceded by a blank line, unless such a comment is preceded by code. + +Comments which are not boxed comments may be formatted, which means that +the line is broken to fit within a right margin and left-filled with +whitespace. Single newlines are equivalent to a space, but blank lines +(two or more newlines in a row) are taken to mean a paragraph break. +Formatting of comments which begin after the first column is enabled +with the \(oq-fca\(cq option. To format those beginning in column one, +specify \(oq-fc1\(cq. Such formatting is disabled by default. + +The right margin for formatting defaults to 78, but may be changed with +the \(oq-lc\(cq option. If the margin specified does not allow the +comment to be printed, the margin will be automatically extended for the +duration of that comment. The margin is not respected if the comment is +not being formatted. + +If the \(oq-fnc\(cq option is specified, all comments with \(oq/*\(cq +embedded will have that character sequence replaced by a space followed +by the character \(oq*\(cq thus eliminating nesting. + +If the comment begins a line (i.e., there is no program text to its +left), it will be indented to the column it was found in unless the +comment is within a block of code. In that case, such a comment will be +aligned with the indented code of that block (unless the comment began +in the first column). This alignment may be affected by the \(oq-d\(cq +option, which specifies an amount by which such comments are moved to +the \fIleft\fR, or unindented. For example, \(oq-d2\(cq places comments +two spaces to the left of code. By default, comments are aligned with +code, unless they begin in the first column, in which case they are left +there by default --- to get them aligned with the code, specify \(oq-fc1\(cq. + +Comments to the right of code will appear by default in column 33. +This may be changed with one of three options. \(oq-c\(cq will specify +the column for comments following code, \(oq-cd\(cq specifies the +column for comments following declarations, and \(oq-cp\(cq specifies +the column for comments following preprocessor directives \fB#else\fR +and \fB#endif\fR. \(oq-dj\(cq together with \(oq-cd0\(cq can be used +to suppress alignment of comments to the right of declarations, causing the +comment to follow one tabstop from the end of the declaration. Normally \(oq-cd0\(cq +causes \(oq-c\(cq to become effective. + +If the code to the left of the comment exceeds the beginning column, +the comment column will be extended to the next tabstop column past +the end of the code, unless the \(oq-ntac\(cq option is specified. +In the case of preprocessor directives,comments are extended to to one +space past the end of the directive. This extension lasts only for +the output of that particular comment. + +The \(oq-cdb\(cq option places the comment delimiters on blank lines. +Thus, a single line comment like \fB/* Loving hug */\fR can be +transformed into: + +.in +5 +.nf +.na +/* + Loving hug + */ +.in -5 +.ad +.fi + +Stars can be placed at the beginning of multi-line comments with the +\(oq-sc\(cq option. Thus, the single-line comment above can be +transformed (with \(oq-cdb -sc\(cq) into: + +.in +5 +.nf +.na +/* + * Loving hug + */ +.in -5 +.ad +.fi + +.SH "STATEMENTS" + +The \(oq-br\(cq or \(oq-bl\(cq option specifies how to format braces. + +The \(oq-br\(cq option formats statement braces like this: + +.in +5 +.nf +.na +if (x > 0) { + x--; +} +.in -5 +.ad +.fi + +The \(oq-bl\(cq option formats them like this: + +.in +5 +.nf +.na +if (x > 0) + { + x--; + } +.in -5 +.ad +.fi + +If you use the \(oq-bl\(cq option, you may also want to specify the +\(oq-bli\(cq option. This option specifies the number of spaces by +which braces are indented. \(oq-bli2\(cq, the default, gives the +result shown above. \(oq-bli0\(cq results in the following: + +.in +5 +.nf +.na +if (x > 0) +{ + x--; +} +.in -5 +.ad +.fi + +If you are using the \(oq-br\(cq option, you probably want to also use +the \(oq-ce\(cq option. This causes the \fBelse\fR in an if-then-else +construct to cuddle up to the immediately preceding \(oq}\(cq. For +example, with \(oq-br -ce\(cq you get the following: + +.in +5 +.nf +.na +if (x > 0) { + x--; +} else { + fprintf (stderr, "...something wrong?\\n"); +} +.in -5 +.ad +.fi + +With \(oq-br -nce\(cq that code would appear as + +.in +5 +.nf +.na +if (x > 0) { + x--; +} +else { + fprintf (stderr, "...something wrong?\\n"); +} +.in -5 +.ad +.fi + +An exception to the behavior occurs when there is a comment between the +right brace and the subsequent else statement. While the \(oq-br\(cq +option will cause a left brace to jump over the comment, the else does +not jump over the comment to cuddle because it has a strong likelihood +of changing the meaning of the comment. + +The \(oq-cdw\(cq option causes the \fBwhile\fR in a do-while +loop to cuddle up to the immediately preceding \(oq}\(cq. For +example, with \(oq-cdw\(cq you get the following: + +.in +5 +.nf +.na +do { + x--; +} while (x); +.in -5 +.ad +.fi + +With \(oq-ncdw\(cq that code would appear as + +.in +5 +.nf +.na +do { + x--; +} +while (x); +.in -5 +.ad +.fi + +The \(oq-slc\(cq option allows for an unbraced conditional and its inner +statement to appear on the same line. For example: + +.in +5 +.nf +.na +if (x) x--; +else x++; +.in -5 +.ad +.fi + +Without \(oq-slc\(cq that code would appear as + +.in +5 +.nf +.na +if (x) + x--; +else + x++; +.in -5 +.ad +.fi + +The \(oq-cli\(cq option specifies the number of spaces that case labels +should be indented to the right of the containing \fBswitch\fR +statement. + +The default gives code like: + +.in +5 +.nf +.na +switch (i) + { + case 0: + break; + case 1: + { + ++i; + } + default: + break; + } +.in -5 +.ad +.fi + +Using the \(oq-cli2\(cq that would become: + +.in +5 +.nf +.na +switch (i) + { + case 0: + break; + case 1: + { + ++i; + } + default: + break; + } +.in -5 +.ad +.fi + +The indentation of the braces below a case statement can be +controlled with the \(oq-cbi\fIn\fR\(cq option. For example, +using \(oq-cli2 -cbi0\(cq results in: + +.in +5 +.nf +.na +switch (i) + { + case 0: + break; + case 1: + { + ++i; + } + default: + break; + } +.in -5 +.ad +.fi + +If a semicolon is on the same line as a \fBfor\fR or \fBwhile\fR +statement, the \(oq-ss\(cq option will cause a space to be placed before +the semicolon. This emphasizes the semicolon, making it clear that the +body of the \fBfor\fR or \fBwhile\fR statement is an empty statement. +\(oq-nss\(cq disables this feature. + +The \(oq-pcs\(cq option causes a space to be placed between the name of +the procedure being called and the \(oq(\(cq (for example, \fBputs\ ("Hi");\fR. The \(oq-npcs\(cq option would give \fBputs("Hi");\fR). + + +If the \(oq-cs\(cq option is specified, \fBindent\fR puts a space between +a cast operator and the object to be cast. The \(oq-ncs\(cq ensures that there +is no space between the cast operator and the object. Remember that \fBindent\fR +only knows about the standard C data types and so cannot recognise user-defined types +in casts. Thus \fB(mytype)thing\fR is not treated as a cast. + +The \(oq-bs\(cq option ensures that there is a space between the +keyword \fBsizeof\fR and its argument. In some versions, this is +known as the \(oqBill_Shannon\(cq option. + +The \(oq-saf\(cq option forces a space between a \fBfor\fR +and the following parenthesis. This is the default. + +The \(oq-sai\(cq option forces a space between a \fBif\fR +and the following parenthesis. This is the default. + +The \(oq-saw\(cq option forces a space between a \fBwhile\fR +and the following parenthesis. This is the default. + +The \(oq-prs\(cq option causes all parentheses to be separated with +a space from whatever is between them. For example, using \(oq-prs\(cq +results in code like: + +.in +5 +.nf +.na + while ( ( e_code - s_code ) < ( dec_ind - 1 ) ) + { + set_buf_break ( bb_dec_ind ); + *e_code++ = \(cq \(cq; + } +.in -5 +.ad +.fi + +.SH "DECLARATIONS" + +By default \fBindent\fR will line up identifiers, in the column +specified by the \(oq-di\(cq option. For example, \(oq-di16\(cq makes +things look like: + +.in +5 +.nf +.na +int foo; +char *bar; +.in -5 +.ad +.fi + +Using a small value (such as one or two) for the \(oq-di\(cq option can +be used to cause the identifiers to be placed in the first available +position; for example: + +.in +5 +.nf +.na +int foo; +char *bar; +.in -5 +.ad +.fi + +The value given to the \(oq-di\(cq option will still affect variables +which are put on separate lines from their types, for example +\(oq-di2\(cq will lead to: + +.in +5 +.nf +.na +int + foo; +.in -5 +.ad +.fi + +If the \(oq-bc\(cq option is specified, a newline is forced after each +comma in a declaration. For example, + +.in +5 +.nf +.na +int a, + b, + c; +.in -5 +.ad +.fi + +With the \(oq-nbc\(cq option this would look like + +.in +5 +.nf +.na +int a, b, c; +.in -5 +.ad +.fi + +The \(oq-bfda\(cq option causes a newline to be forced after the comma +separating the arguments of a function declaration. The arguments will +appear at one indention level deeper than the function declaration. This +is particularly helpful for functions with long argument lists. +The option \(oq-bfde\(cq causes a newline to be forced before the closing +bracket of the function declaration. For both options the \(cqn\(cq setting is the default: +-nbfda and -nbfde. + + +For +example, + +.in +5 +.nf +.na +void foo (int arg1, char arg2, int *arg3, long arg4, char arg5); +.in -5 +.ad +.fi +With the \(oq-bfda\(cq option this would look like + +.in +5 +.nf +.na +void foo ( + int arg1, + char arg2, + int *arg3, + long arg4, + char arg5); +.in -5 +.ad +.fi + +With, in addition, the \(oq-bfde\(cq option this would look like + +.in +5 +.nf +.na +void foo ( + int arg1, + char arg2, + int *arg3, + long arg4, + char arg5 + ); +.in -5 +.ad +.fi + +The \(oq-psl\(cq option causes the type of a procedure being defined to +be placed on the line before the name of the procedure. This style is +required for the \fBetags\fR program to work correctly, as well as some +of the \fBc-mode\fR functions of Emacs. + +You must use the \(oq-T\(cq +option to tell \fBindent\fR the name of all the typenames in your +program that are defined by \fBtypedef\fR. \(oq-T\(cq can be specified +more than once, and all names specified are used. For example, if your +program contains + +.in +5 +.nf +.na +typedef unsigned long CODE_ADDR; +typedef enum {red, blue, green} COLOR; +.in -5 +.ad +.fi + +you would use the options \(oq-T CODE_ADDR -T COLOR\(cq. + + +The \(oq-brs\(cq or \(oq-bls\(cq option specifies how to format braces +in struct declarations. The \(oq-brs\(cq option formats braces like +this: + +.in +5 +.nf +.na +struct foo { + int x; +}; +.in -5 +.ad +.fi + +The \(oq-bls\(cq option formats them like this: + +.in +5 +.nf +.na +struct foo +{ + int x; +}; +.in -5 +.ad +.fi + + +Similarly to the structure brace \(oq-brs\(cq and \(oq-bls\(cq options, + the function brace options \(oq-brf\(cq or \(oq-blf\(cq specify how to format the braces +in function definitions. The \(oq-brf\(cq option formats braces like +this: + +.in +5 +.nf +.na +int one(void) { + return 1; +}; +.in -5 +.ad +.fi + +The \(oq-blf\(cq option formats them like this: + +.in +5 +.nf +.na +int one(void) +{ + return 1; +}; +.in -5 +.ad +.fi + + +The \(oq-sar\(cq option affects how \fBindent\fR will render initializer +lists. Without \(oq-sar\(cq they are formatted like this: + +.in +5 +.nf +.na +int a[] = {1, 2, 3, 4}; + +struct s { + const char *name; + int x; +} a[] = { + {"name", 0}, + {"a", 1} +}; +.in -5 +.ad +.fi + +With \(oq-sar\(cq they are formatted like this, with spaces inside the +braces: + +.in +5 +.nf +.na +int a[] = { 1, 2, 3, 4 }; + +struct s { + const char *name; + int x; +} a[] = { + { "name", 0 }, + { "a", 1 } +}; +.in -5 +.ad +.fi + +.SH "INDENTATION" + +The most basic, and most controversial issues with regard to code +formatting is precisely how indentation should be acoomplished. +Fortunately, \fBindent\fR supports several different styles of +identation. The default is to use tabs for indentation, which is +specified by the \(oq-ut\(cq option. Assuming the default tab size of +8, the code would look like this: + +.in +5 +.nf +.na +int a(int b) +{ + return b; +|------| + 1 tab +} +.in -5 +.ad +.fi + +For those that prefer spaces to tabs, \(oqindent\(cq provides the +\(oq-nut\(cq option. The same code would look like this: + +.in +5 +.nf +.na +int a(int b) +{ + return b; +|------| +8 spaces +} +.in -5 +.ad +.fi + +Another issue in the formatting of code is how far each line should be +indented from the left margin. When the beginning of a statement such +as \fBif\fR or \fBfor\fR is encountered, the indentation level is +increased by the value specified by the \(oq-i\(cq option. For example, +use \(oq-i8\(cq to specify an eight character indentation for each +level. When a statement is broken across two lines, the second line is +indented by a number of additional spaces specified by the \(oq-ci\(cq +option. \(oq-ci\(cq defaults to 0. However, if the \(oq-lp\(cq option is +specified, and a line has a left parenthesis which is not closed on that +line, then continuation lines will be lined up to start at the character +position just after the left parenthesis. This processing also applies +to \(oq[\(cq and applies to \(oq{\(cq when it occurs in initialization +lists. For example, a piece of continued code might look like this with +\(oq-nlp -ci3\(cq in effect: + +.in +5 +.nf +.na + p1 = first_procedure (second_procedure (p2, p3), + third_procedure (p4, p5)); +.in -5 +.ad +.fi + +With \(oq-lp\(cq in effect the code looks somewhat clearer: + +.in +5 +.nf +.na + p1 = first_procedure (second_procedure (p2, p3), + third_procedure (p4, p5)); +.in -5 +.ad +.fi + +When a statement is broken in between two or more paren pairs (...), +each extra pair causes the indentation level extra indentation: + +.in +5 +.nf +.na +if ((((i < 2 && + k > 0) || p == 0) && + q == 1) || + n = 0) +.in -5 +.ad +.fi + +The option \(oq-ip\fIN\fR\(cq can be used to set the extra offset per paren. +For instance, \(oq-ip0\(cq would format the above as: + +.in +5 +.nf +.na +if ((((i < 2 && + k > 0) || p == 0) && + q == 1) || + n = 0) +.in -5 +.ad +.fi + +.B indent\fR assumes that tabs are placed at regular intervals of both +input and output character streams. These intervals are by default 8 +columns wide, but (as of version 1.2) may be changed by the \(oq-ts\(cq +option. Tabs are treated as the equivalent number of spaces. + +By default, \fBindent\fR will use tabs to indent as far as possible, +and then pad with spaces until the desired position is reached. However, +with the \(oq-as\(cq option, spaces will be used for alignment beyond +the current indentation level. By default, assuming \(oq-lp\(cq is +enabled, the code would be indented like so (\(oqt\(cq represents tabs, +\(oqs\(cq represents spaces): + +.in +5 +.nf +.na +unsigned long really_long_proc_name(unsigned long x, unsigned long y, + int a) +|------||-------||------||-------|__ + t t t t ss +{ + p1 = first_procedure (second_procedure (p2, p3), + third_procedure (p4, p5)); +|------||------||------|_____ + t t t sssss +} +.in -5 +.ad +.fi + +This is fine, if you assume that whoever is reading the code will honor +your assumption of 8-space tabs. If the reader was using 4-space tabs, +it would look like this: + +.in +5 +.nf +.na +unsigned long really_long_proc_name(unsigned long x, unsigned long y, + int a) +|---||---||---||---|__ + t t t t ss +{ + p1 = first_procedure (second_procedure (p2, p3), + third_procedure (p4, p5)); +|---||---||---|______ + t t t ssssss +} +.in -5 +.ad +.fi + +The \(oq-as\(cq option fixes this so that the code will appear consistent +regardless of what tab size the user users to read the code. This looks +like: + +.in +5 +.nf +.na +unsigned long really_long_proc_name(unsigned long x, unsigned long y, + int a) +____________________________________ +ssssssssssssssssssssssssssssssssssss +{ + p1 = first_procedure (second_procedure (p2, p3), + third_procedure (p4, p5)); +|------|______________________ + t ssssssssssssssssssssss +} +.in -5 +.ad +.fi + +The indentation of type declarations in old-style function definitions +is controlled by the \(oq-ip\(cq parameter. This is a numeric parameter +specifying how many spaces to indent type declarations. For example, +the default \(oq-ip5\(cq makes definitions look like this: + +.in +5 +.nf +.na +char * +create_world (x, y, scale) + int x; + int y; + float scale; +{ + . . . +} +.in -5 +.ad +.fi + +For compatibility with other versions of indent, the option \(oq-nip\(cq +is provided, which is equivalent to \(oq-ip0\(cq. + +ANSI C allows white space to be placed on preprocessor command lines +between the character \(oq#\(cq and the command name. By default, +.B indent\fR removes this space, but specifying the \(oq-lps\(cq option +directs \fBindent\fR to leave this space unmodified. The option \(oq-ppi\(cq +overrides \(oq-nlps\(cq and \(oq-lps\(cq. + +This option can be used to request that preprocessor conditional statements can +be indented by to given number of spaces, for example with the option \(oq-ppi 3\(cq + +.in +5 +.nf +.na +#if X +#if Y +#define Z 1 +#else +#define Z 0 +#endif +#endif +.in -5 +.ad +.fi +becomes +.in +5 +.nf +.na +#if X +# if Y +# define Z 1 +# else +# define Z 0 +# endif +#endif +.in -5 +.ad +.fi + +This option sets the offset at which a label (except case labels) +will be positioned. If it is set to zero or a positive number, this indicates how +far from the left margin to indent a label. If it is set to a negative number, +this indicates how far back from the current indent level to place the label. +The default setting is -2 which matches the behaviour of earlier versions of indent. +Note that this parameter does not affect the placing of case labels; see the +\(oq-cli\(cq parameter for that. For example with the option \(oq-il 1\(cq + +.in +5 +.nf +.na +group +function() +{ + if (do_stuff1() == ERROR) + goto cleanup1; + + if (do_stuff2() == ERROR) + goto cleanup2; + + return SUCCESS; + + cleanup2: + do_cleanup2(); + + cleanup1: + do_cleanup1(); + + return ERROR; +} +.in -5 +.ad +.fi +becomes +.in +5 +.nf +.na +group +function() +{ + if (do_stuff1() == ERROR) + goto cleanup1; + + if (do_stuff2() == ERROR) + goto cleanup2; + + return SUCCESS; + + cleanup2: + do_cleanup2(); + + cleanup1: + do_cleanup1(); + + return ERROR; +} +.in -5 +.ad +.fi + +.SH "BREAKING LONG LINES" + +With the option \(oq-l\fIn\fR\(cq, or \(oq--line-length\fIn\fR\(cq, it is +possible to specify the maximum length of a line of C code, not including +possible comments that follow it. + +When lines become longer than the specified line length, GNU \fBindent\fR +tries to break the line at a logical place. This is new as of version 2.1 +however and not very intelligent or flexible yet. + +Currently there are three options that allow one to interfere with the +algorithm that determines where to break a line. + +The \(oq-bbo\(cq option causes GNU \fBindent\fR to prefer to break +long lines before the boolean operators \fB&&\fR and \fB||\fR. The +\(oq-nbbo\(cq option causes GNU \fBindent\fR not have that +preference. For example, the default option \(oq-bbo\(cq (together +with \(oq--line-length60\(cq and \(oq--ignore-newlines\(cq) makes code +look like this: + +.in +5 +.nf +.na + if (mask + && ((mask[0] == \(cq\\0\(cq) + || (mask[1] == \(cq\\0\(cq + && ((mask[0] == \(cq0\(cq) || (mask[0] == \(cq*\(cq))))) +.in -5 +.ad +.fi + +Using the option \(oq-nbbo\(cq will make it look like this: + +.in +5 +.nf +.na + if (mask && + ((mask[0] == \(cq\\0\(cq) || + (mask[1] == \(cq\\0\(cq && + ((mask[0] == \(cq0\(cq) || (mask[0] == \(cq*\(cq))))) +.in -5 +.ad +.fi + +The default \(oq-hnl\(cq, however, honours newlines in the input file by +giving them the highest possible priority to break lines at. For example, +when the input file looks like this: + +.in +5 +.nf +.na + if (mask + && ((mask[0] == \(cq\\0\(cq) + || (mask[1] == \(cq\\0\(cq && ((mask[0] == \(cq0\(cq) || (mask[0] == \(cq*\(cq))))) +.in -5 +.ad +.fi + +then using the option \(oq-hnl\(cq, or \(oq--honour-newlines\(cq, +together with the previously mentioned \(oq-nbbo\(cq and +\(oq--line-length60\(cq, will cause the output not to be what is given +in the last example but instead will prefer to break at the positions +where the code was broken in the input file: + +.in +5 +.nf +.na + if (mask + && ((mask[0] == \(cq\\0\(cq) + || (mask[1] == \(cq\\0\(cq && + ((mask[0] == \(cq0\(cq) || (mask[0] == \(cq*\(cq))))) +.in -5 +.ad +.fi + +The idea behind this option is that lines which are too long, but are already +broken up, will not be touched by GNU \fBindent\fR. Really messy code +should be run through \fBindent\fR at least once using the +\(oq--ignore-newlines\(cq option though. + +The \(oq-gts\(cq option affects how the gettext standard macros \fB_()\fR and \fBN_()\fR +are treated. The default behavior (or the use of \(oq-ngts\(cq) causes indent to +treat them as it does other functions, so that a long string is broken like the following +example. + +.in +5 +.nf +.na + if (mask) + { + warning (_ + ("This is a long string that stays together.")); + } +.in -5 +.ad +.fi + +With the \(oq-gts\(cq option, the underscore is treated as a part of the string, keeping +it tied to the string, and respecting the fact that gettext is unobtrusively providing +a localized string. This only works if \fB_("\fR is together as a unit at the beginning +of the string and \fB")\fR is together as a unit at the end. + +.in +5 +.nf +.na + if (mask) + { + warning + (_("This is a long string that stays together.")); + } +.in -5 +.ad +.fi + +.SH "DISABLING FORMATTING" + +Formatting of C code may be disabled for portions of a program by +embedding special \fIcontrol comments\fR in the program. To turn off +formatting for a section of a program, place the disabling control +comment \fB/* *INDENT-OFF* */\fR on a line by itself just before that +section. Program text scanned after this control comment is output +precisely as input with no modifications until the corresponding +enabling comment is scanned on a line by itself. The enabling control +comment is \fB/* *INDENT-ON* */\fR, and any text following the comment +on the line is also output unformatted. Formatting begins again with +the input line following the enabling control comment. + +More precisely, \fBindent\fR does not attempt to verify the closing +delimiter (\fB*/\fR) for these C comments, and any whitespace on the +line is totally transparent. + +These control comments also function in their C++ formats, namely +.B // *INDENT-OFF*\fR and \fB// *INDENT-ON*\fR. + +It should be noted that the internal state of \fBindent\fR remains +unchanged over the course of the unformatted section. Thus, for +example, turning off formatting in the middle of a function and +continuing it after the end of the function may lead to bizarre +results. It is therefore wise to be somewhat modular in selecting code +to be left unformatted. + +As a historical note, some earlier versions of \fBindent\fR produced +error messages beginning with \fB*INDENT**\fR. These versions of +.B indent\fR were written to ignore any input text lines which began +with such error messages. I have removed this incestuous feature from +GNU \fBindent\fR. + +.SH "MISCELLANEOUS OPTIONS" + +To find out what version of \fBindent\fR you have, use the command +.B indent -version\fR. This will report the version number of +.B indent\fR, without doing any of the normal processing. + +The \(oq-v\(cq option can be used to turn on verbose mode. When in +verbose mode, \fBindent\fR reports when it splits one line of input +into two more more lines of output, and gives some size statistics at +completion. + +The \(oq-pmt\(cq option causes \fBindent\fR to preserve the access +and modification times on the output files. Using this option +has the advantage that running indent on all source and header +files in a project won\(cqt cause \fBmake\fR to rebuild all targets. +This option is only available on Operating Systems that have the +POSIX \fButime(2)\fR function. + +.SH "BUGS" + +Please report any bugs to bug-indent@gnu.org. + +When \fBindent\fR is run twice on a file, with the same profile, +it should \fInever\fR change that file the second time. With the +current design of \fBindent\fR, this can not be guaranteed, +and it has not been extensively tested. + +.B indent\fR does not understand C. In some cases this leads to +the inability to join lines. The result is that running a file +through \fBindent\fR is \fIirreversible\fR, even if the used input +file was the result of running \fBindent\fR with a given profile +(\(oq.indent.pro\(cq). + +While an attempt was made to get \fBindent\fR working for C++, it +will not do a good job on any C++ source except the very simplest. + +.B indent\fR does not look at the given \(oq--line-length\(cq option +when writing comments to the output file. This results often in comments +being put far to the right. In order to prohibit \fBindent\fR from +joining a broken line that has a comment at the end, make sure that the +comments start on the first line of the break. + +.B indent\fR does not count lines and comments (see the \(oq-v\(cq +option) when \fBindent\fR is turned off with +.B /* *INDENT-OFF* */\fR. + +Comments of the form \fB/*UPPERCASE*/\fR are not treated as comment but as an +identifier, causing them to be joined with the next line. This renders +comments of this type useless, unless they are embedded in the code to +begin with. + +.SH "COPYRIGHT" + +The following copyright notice applies to the \fBindent\fR program. +The copyright and copying permissions for this manual appear near the +beginning of \(oqindent.texinfo\(cq and \(oqindent.info\(cq, and near the +end of \(oqindent.1\(cq. + +.nf +.na +Copyright (c) 2015 Tim Hentenaar. +Copyright (c) 2001 David Ingamells. +Copyright (c) 1999 Carlo Wood. +Copyright (c) 1995, 1996 Joseph Arceneaux. +Copyright (c) 1989, 1992, 1993, 1994, 1995, 1996, 2014 Free Software Foundation +Copyright (c) 1985 Sun Microsystems, Inc. +Copyright (c) 1980 The Regents of the University of California. +Copyright (c) 1976 Board of Trustees of the University of Illinois. +All rights reserved. + +Redistribution and use in source and binary forms are permitted +provided that the above copyright notice and this paragraph are +duplicated in all such forms and that any documentation, +advertising materials, and other materials related to such +distribution and use acknowledge that the software was developed +by the University of California, Berkeley, the University of Illinois, +Urbana, and Sun Microsystems, Inc. The name of either University +or Sun Microsystems may not be used to endorse or promote products +derived from this software without specific prior written permission. +THIS SOFTWARE IS PROVIDED \(oq\(oqAS IS\(cq\(cq AND WITHOUT ANY EXPRESS OR +IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR +PURPOSE. +.ad +.fi + +.SH "Options\(cq Cross Key" + +Here is a list of options alphabetized by long option, to help you find +the corresponding short option. + + +.in +5 +.nf +.na +--align-with-spaces -as +--blank-lines-after-commas -bc +--blank-lines-after-declarations -bad +--blank-lines-after-procedures -bap +--blank-lines-before-block-comments -bbb +--braces-after-if-line -bl +--braces-after-func-def-line -blf +--brace-indent -bli +--braces-after-struct-decl-line -bls +--braces-on-if-line -br +--braces-on-func-def-line -brf +--braces-on-struct-decl-line -brs +--break-after-boolean-operator -nbbo +--break-before-boolean-operator -bbo +--break-function-decl-args -bfda +--break-function-decl-args-end -bfde +--case-indentation -cli\fIn\fR +--case-brace-indentation -cbi\fIn\fR +--comment-delimiters-on-blank-lines -cdb +--comment-indentation -c\fIn\fR +--continuation-indentation -ci\fIn\fR +--continue-at-parentheses -lp +--cuddle-do-while -cdw +--cuddle-else -ce +--declaration-comment-column -cd\fIn\fR +--declaration-indentation -di\fIn\fR +--dont-break-function-decl-args -nbfda +--dont-break-function-decl-args-end -nbfde +--dont-break-procedure-type -npsl +--dont-cuddle-do-while -ncdw +--dont-cuddle-else -nce +--dont-format-comments -nfca +--dont-format-first-column-comments -nfc1 +--dont-line-up-parentheses -nlp +--dont-left-justify-declarations -ndj +--dont-space-special-semicolon -nss +--dont-star-comments -nsc +--dont-tab-align-comments -ntac +--else-endif-column -cp\fIn\fR +--format-all-comments -fca +--format-first-column-comments -fc1 +--gnu-style -gnu +--honour-newlines -hnl +--ignore-newlines -nhnl +--ignore-profile -npro +--indent-label -il\fIn\fR +--indent-level -i\fIn\fR +--k-and-r-style -kr +--leave-optional-blank-lines -nsob +--leave-preprocessor-space -lps +--left-justify-declarations -dj +--line-comments-indentation -d\fIn\fR +--line-length -l\fIn\fR +--linux-style -linux +--no-blank-lines-after-commas -nbc +--no-blank-lines-after-declarations -nbad +--no-blank-lines-after-procedures -nbap +--no-blank-lines-before-block-comments -nbbb +--no-comment-delimiters-on-blank-lines -ncdb +--no-space-after-casts -ncs +--no-parameter-indentation -nip +--no-space-after-for -nsaf +--no-space-after-function-call-names -npcs +--no-space-after-if -nsai +--no-space-after-parentheses -nprs +--no-space-after-while -nsaw +--no-tabs -nut +--no-verbosity -nv +--original -orig +--parameter-indentation -ip\fIn\fR +--paren-indentation -pi\fIn\fR +--preserve-mtime -pmt +--preprocessor-indentation -ppi\fIn\fR +--procnames-start-lines -psl +--remove-preprocessor-space -nlps +--single-line-conditionals -slc +--space-after-cast -cs +--space-after-for -saf +--space-after-if -sai +--space-after-parentheses -prs +--space-after-procedure-calls -pcs +--space-after-while -saw +--space-special-semicolon -ss +--spaces-around-initializers -sar +--standard-output -st +--start-left-side-of-comments -sc +--struct-brace-indentation -sbi\fIn\fR +--swallow-optional-blank-lines -sob +--tab-size -ts\fIn\fR +--use-tabs -ut +--verbose -v +.in -5 +.ad +.fi + +.SH "RETURN VALUE" +.IP \(bu 2 +0 means no errors or warnings were found during a successful invocation of +the program. +.br +.IP \(bu 2 +2 is returned if errors occur during formatting which do not prevent completion +of the formatting, but which appear to be manifested by incorrect code (i.e. code +which wouldn't compile). +.br +.IP \(bu 2 +3 is returned if formatting of a file is halted because of an error with the file +which prevents completion of formatting. If more than one input file was specified, +indent continues to the next file. +.br +.IP \(bu 2 +4 is returned if a serious internal problem occurs and the entire indent process +is terminated, even if all specified files have not been processed. +.br +.IP \(bu 2 +64 is returned if an invocation problem (like an incorrect option) prevents +any formatting to occur. +.SH FILES +.br +.nf +.\" set tabstop to longest possible filename, plus a wee bit +.ta \w'$HOME/.indent.pro 'u +\fI$HOME/.indent.pro\fR holds default options for indent. +.SH "AUTHORS" +.br +Tim Hentenaar +.br +Carlo Wood +.br +Joseph Arceneaux +.br +Jim Kingdon +.br +David Ingamells +.SH "HISTORY" +Derived from the UCB program "indent". +.SH "COPYING" +Copyright (C) 1989, 1992, 1993, 1994, 1995, 1996, 2014, 2015 Free Software Foundation, Inc. +Copyright (C) 1995, 1996 Joseph Arceneaux. +Copyright (C) 1999 Carlo Wood. +Copyright (C) 2001 David Ingamells. +Copyright (C) 2013 Łukasz Stelmach. +Copyright (C) 2015 Tim Hentenaar. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + + |