Provided by: dist_3.5-236-1_all bug

NAME

       manilist - report status of files in a source directory

SYNOPSIS

       manilist  [ -abcdhnptV ] [ -i extension ] [ -f manifest ] [ -p format ] [ -s string ] [ -w
       which ] [ -x extension ] [ -C separator ] [ -I included ] [ -L colsize ] [ -X excluded ] [
       files or directories ]

DESCRIPTION

       Manilist  scans  a  source  directory  and  produces  a report on the status of each file:
       whether it is up-to-date or not with respect to patchlevel.h  ,  if  it  is  missing  from
       MANIFEST.new,  and  some  other useful information which may be dynamically configured. It
       can be use to maintain a MANIFEST.new file, produce a detailed listing  and  status  of  a
       group  of  directories,  etc...  The rich set of options concur to make manilist a perfect
       low-level tool.

       Under its simplest invocation form at the top  level  directory  of  a  package,  with  no
       arguments,  manilist will scan the MANIFEST.new and produce a report on the status of each
       file listed there. Each line starts with a single character flag which indicates the state
       of the file, followed by the name of the file.

       What  happens  in fact is more complex than that. Manilist scans the MANIFEST.new file and
       then loops over all the files listed there. Internally, manilist  maintains  an  inclusion
       and  an  exclusion list, both specifying extensions for files. For instance, the inclusion
       list could be ('.c', '.h') and the exclusion ('.o', ',v') so that C sources  are  included
       and object or RCS files excluded. By default, all files but those excluded are used.  Some
       other selections may be applied at this stage, as will be explained later  on.  For  those
       files  which pass this selection process, a report is issued according to a report format,
       which by default is "A:%c %n".  The letter A (or anything before the initial ':' character
       is  the  file  selection  specification  we've  been  talking  about. The remaining is the
       formatting, a string which is printed as-is, modulo some escape sequences.  It so  happens
       that %c is the character flag and %n is the name of the current file.

       Generally speaking, manilist should be regarded as a tool which emits configurable reports
       on a set of files, selectively picking them among a  list  or  by  directly  scanning  the
       directories to see what's out there...

       By specifying a set of directories or files as arguments on the command line, you restrict
       the scanning area, limiting to reports concerning those files or directories.  If  you  do
       not  specify  any,  manilist  restricts  its  report  to  the  current  directory  and its
       subdirectories, unless the -t option is given.

OPTIONS

       Manilist recognizes the following options:

       -a             Make a report for all the files, regardless of what  is  specified  by  the
                      included and excluded suffix lists.

       -b             Assume  current directory is the base (root) of the package tree. When this
                      option is not specified, manilist will look for a .package file to indicate
                      the  root directory of the package (also called the top) and complain if it
                      does not find it.

       -c             Check  files  against  those  listed  in  MANIFEST.new  (or  whatever  file
                      specified via the -f option) and report discrepancies via the %c macro.

       -d             Dump  included  and excluded suffix lists on stderr, extensions being space
                      separated. A good way to know the default lists  is  to  run:  manilist  -f
                      /dev/null -bd.

       -f manifest    Specify an alternate manifest file, the default being to use MANIFEST.new.

       -h             Print the usage help message and exit.

       -i extensions  Add  new  extensions  to  the included suffix list. The extensions argument
                      must list the suffixes separated by spaces, as in -i '.ph .pl' to add  both
                      .ph  and  .pl  to the existing suffixes. Note that the argument needs to be
                      quoted to protect spaces against shell interpretation.

       -n             Do not use any manifest file. Rather scan the directories and act  as  with
                      all the files there were already listed in a manifest.

       -p format      Set  the  new  printing  format,  which has the form selection:string, with
                      selection being a list of single letters specifying which  files  from  the
                      manifest are to be used for reports, and string being a message to print as
                      report, with some macro substitutions. It is also possible to  have  column
                      formatting  by  specifying a '|' inside the string to delimit the different
                      columns you wish to see. See also -C and -L for more formatting parameters.

       -s string      Specify the string part of the  printing  format  (see  -p  for  a  general
                      description  of  the  format). Available macros are listed further down the
                      manual page.

       -t             Start from the top directory  (the  root  directory  of  the  distribution)
                      regardless  of  the  current  directory.  There  must be a .package file to
                      indicate what the top directory is.

       -w selection   Specifiy the selection part of the printing  format.  Available  selections
                      will be discussed later.

       -x extensions  Add  new  extensions  to  the excluded suffix list. The extensions argument
                      must list the suffixes separated by spaces, as in -x '.s .p' to add both .s
                      and  .p  to the existing list. Note that the argument needs to be quoted to
                      protect spaces against shell interpretation.

       -C separator   Give the column separator, which  is  to  be  used  in  place  of  the  '|'
                      character in the report format string. By default, it is a single space.

       -I included    Specify  a  new  list  of  suffixes  to  be  included  in the reports. This
                      overrides the original default list (whereas -i is used to add suffixes  to
                      the list). Suffixes must be space separated.

       -L colsize     When  using  column  formatting  (the  '|'  character  being used to denote
                      columns), this option may be used to  specify  the  maximum  column  width,
                      separating each width by a single ','. Leaving a width unspecified does not
                      impose any limit on its width.  For  instance,  if  the  format  string  is
                      %n|%d|%t,   one   could   limit   the   middle  column  (descriptions  from
                      MANIFEST.new) to 40 characters and  the  name  column  (first  one)  to  15
                      characters,  leaving  the  last  one  with  no  imposed limits, by using -L
                      15,40,.

       -V             Print version number and exit.

       -X excluded    Specify a new list  of  suffixes  to  be  excluded  in  the  reports.  This
                      overrides  the original default list (whereas -x is used to add suffixes to
                      the list). Suffixes must be space separated.

USING FORMATS

       The flexibility of manilist is brought by its use  of  a  dynamic  formatting  string  for
       providing  its reports. It is possible to specify a format via the -p option or just parts
       of it: the text string via -s and the file selection with -w.

   File Selection
       The leading part of the formatting string tells manilist which files you wish  to  see  in
       the final report. Available selectors are:

       A    All  the  files but the excluded ones (i.e. those files whose suffix is listed in the
            exclusion list). This is the default action.
       a    All the files included and/or excluded (shortcut for ix). Note that files  which  are
            neither included nor excluded will not appear in the report.
       d    Report only for directories.
       f    Report only for files.
       i    Only included files are listed.
       m    Only those files or directories found in the manifest are listed.
       n    Only those files or directories not found in the manifest are listed.
       x    Only excluded files are listed.

       When  you  specify more than one letter, the resulting report depends on the nature of the
       selection. For d, f, m and n, a logical union is performed. This means specifying fd or mn
       is  the  same as not specifying anything, but it's less efficient since manilist is forced
       to perform the checks it would otherwise bypass. The i and x  selectors  are  special:  by
       default,  all  the  files  not excluded are reported.  Specifying x also asks for excluded
       files. Specifying i restricts the report to the included files. Using  both  at  the  same
       time (ix) will force a report for files which are included or excluded.

   Macro Substitution
       The string part of the report format can make use of the following macros:

       %c   A character coding the status of the file.
       %d   Description from the manifest file, if any.
       %n   Name of the file (its path from the top directory).
       %s   Size of the file, in bytes.
       %t   Time stamp of the last modification.

   File Status
       The %c macro, giving a single character coding the file status, can expand into one of the
       following.
       .    The file is up to date (not newer than patchlevel.h).
       -    The file is present in the manifest but is missing.
       >    The file has been modified since last patch (newer than patchlevel.h).
       +    The file exists but is not listed in the manifest.
       o    The file exists but is not listed in the manifest and is older than patchlevel.h
       x    The file is listed in the manifest and exists, but has been excluded. Naturally, this
            will appear in the report only if the x selector is given in the report format.
       ?    The file is listed in the manifest, does not exist, and was excluded.

EXAMPLES

       The command

            manilist -ct -p 'ni:%n'

       will  list  all  the  source  files  from  your  distribution which are not listed in your
       MANIFEST.new file. Note that this includes only "source" files, that is to say files whose
       extension  is  listed in the inclusion list.  If you do not wish this restriction, replace
       the formatting string with n:%n (only the excluded files will not appear).

       To build an initial MANIFEST file, use:

            manilist -n -p 'Af:%n' > MANIFEST

       from the top directory. You will eventually want to fill in  descriptions  for  each  file
       listed in the manifest.

FILES

       MANIFEST.new        Default  manifest  file,  listing files and giving a small description
                           for each of them.

AUTHOR

       Raphael Manfredi <Raphael.Manfredi@pobox.com>

SEE ALSO

       manifake(1), makedist(1), pat(1).

                                               ram                                    MANILIST(1)