Provided by: aegis_4.21-2_i386 bug

NAME

       aeannotate - annotated source file listing

SYNOPSIS

       aeannotate [ option...  ] filename
       aeannotate -Help
       aeannotate -List
       aeannotate -VERSion

DESCRIPTION

       The aeannotate command is used to produce an annotated listing of the
       named source file.

       The columns specified by the user (see the --column option, below) are
       used of the left hand side of the output.  Two additional columns are
       always added: the line number and the source code.

       If no columns are specified, the default columns are

                   -column   ’${change date %Y-%m}’   Date      7
                   -column   ’$version’               Version   9
                   -column   ’${change developer}’    Who       8
       The $version string always contains enough information to reproduce the
       entire project baseline at the time of the delta.  The first portion is
       the project branch, and the second portion (following the ‘D’) is the
       delta number; use these to form the -branch and -delta options for an
       aecp(1) command.

       At the end of the listing, accumulated statistics are presented,
       correlated to the unique columns values see in the listing.

OPTIONS

       The following options are understood:

       -COLumn formula  [ heading ][ width ]
               This option may be used to specify columns you wish to see in
               the output.  The formula is in the for of an aesub(5) string.
               The heading is a string to be used as the column heading;
               defaults to the formula if not specified.  The width is the
               width of the columns; defaults to 7 if not specified.

       -File_Statistics
               This option causes file statistics to be appended.  This lists
               the number of lines in the file were changed at the same time
               as another file.  For example, this allows you to see tests
               associated with source files, and vice versa.

       -Help
               This option may be used to obtain more information about how to
               use the aeannotate program.

       -Diff_Option string
               This option may be used to pass addition arguments to the diff
               commands that is run between each delta of the file.  Use with
               caution: poor choice of options can render aeannotate
               inoperable, or yield meaningless results.  Probably the best
               use of this option is to pass the -b option, to ignore white
               space changes, because this ignores the vast majority of
               cosmetic formatting changes, showing you the content changes
               instead.  The -i option, to ignore case, can also be useful for
               case-insensitive languages.

       -Output filename
               This option may be used to specify the output file.  The output
               is sent to the standard output by default.

       -Project name
               This option may be used to select the project of interest.
               When no -Project option is specified, the AEGIS_PROJECT
               environment variable is consulted.  If that does not exist, the
               user’s $HOME/.aegisrc file is examined for a default project
               field (see aeuconf(5) for more information).  If that does not
               exist, when the user is only working on changes within a single
               project, the project name defaults to that project.  Otherwise,
               it is an error.

       See also aegis(1) for options common to all aegis commands.

       All options may be abbreviated; the abbreviation is documented as the
       upper case letters, all lower case letters and underscores (_) are
       optional.  You must use consecutive sequences of optional letters.

       All options are case insensitive, you may type them in upper case or
       lower case or a combination of both, case is not important.

       For example: the arguments "-project, "-PROJ" and "-p" are all
       interpreted to mean the -Project option.  The argument "-prj" will not
       be understood, because consecutive optional characters were not
       supplied.

       Options and other command line arguments may be mixed arbitrarily on
       the command line, after the function selectors.

       The GNU long option names are understood.  Since all option names for
       aeannotate are long, this means ignoring the extra leading ’-’.  The
       "--option=value" convention is also understood.

EXIT STATUS

       The aeannotate command will exit with a status of 1 on any error.  The
       aeannotate command will only exit with a status of 0 if there are no
       errors.

ENVIRONMENT VARIABLES

       See aegis(1) for a list of environment variables which may affect this
       command.  See aepconf(5) for the project configuration file’s project_
       specific field for how to set environment variables for all commands
       executed by Aegis.

EXAMPLES

       If you wanted to list only the year against the lines of the file, use
       this column specification:

                      -column   ’${change date %Y}’   Year   4

       If you wanted to list the developer and the reviewer against the lines
       of the file (commonly called a ‘‘blame’’ listing) use this column
       specification:

                   -column   ’${change developer}’   Develop.   8
                   -column   ’${change reviewer}’    Reviewer   8

       If you wanted to see the change cause of each line, use this column
       specification:

                     -column   ’$version’          Version   9
                     -column   ’${change cause}’   Cause     20

       All of the aesub(5) substitutions are available, however only the
       ${change ...} variants are particularly useful.

       To see only content changes, and ignore changes in indentation
       (assuming you are using GNU diff), use this command:
              aeannotate -diff-opt -b filename

COPYRIGHT

       aeannotate version 4.21
       Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
       2000, 2001, 2002, 2003, 2004, 2005 Peter Miller; All rights reserved.

       The aeannotate program comes with ABSOLUTELY NO WARRANTY; for details
       use the ’aeannotate -VERSion License’ command.  This is free software
       and you are welcome to redistribute it under certain conditions; for
       details use the ’aeannotate -VERSion License’ command.

AUTHOR

       Peter Miller   E-Mail:   millerp@canb.auug.org.au
       /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/